Querying projects in PHP
In the PHP code of a theme or a plugin, you can find one project by its ID or slug, or a list of projects filtered and sorted as you need, and count how many match.
On this page
find() and count() belong to the LS_Sliders class, which exists only while LayerSlider is active. Guard every call with class_exists( 'LS_Sliders' ), so that your code keeps working when LayerSlider isn’t running.
LS_Sliders::find()
LS_Sliders::find( $args = [] )find() takes one argument, which can be left out, and returns each project as an array of its properties. What you pass decides which projects you get:
| Argument | Example | What it returns |
|---|---|---|
| The project’s ID | 12 |
The project with that ID |
| The project’s slug | 'summer-sale' |
The project with that slug |
| An array of IDs | [ 12, 15, 20 ] |
A list of the projects with those IDs, newest first |
| An array of query options, an empty array, or no argument | [ 'limit' => 10 ] |
A list of the projects that match the query options |
In the LayerSlider dashboard, you can put projects into groups. A group is stored in the same database table as the projects, so find() can return a group too.
The lookups by ID, by slug, and by an array of IDs don’t leave anything out: they also return unpublished projects, projects hidden in the dashboard, and groups.
A project’s slug is set in Project Settings › Publish › Project Slug & Keywords.
With a project’s ID or slug, you can also embed the project on a page from PHP.
Query options
With an array of options, find() runs a query, and the options choose which projects it returns, what each one holds, in what order, and how many at a time. There are 9 options, and each one that you leave out takes its default.
| Option | Type | Default | What it is |
|---|---|---|---|
columns |
string | '*' |
The columns to select, as a comma-separated list |
where |
string | '' |
An SQL condition of your own, added to the query with AND as you write it |
exclude |
array | [ 'removed' ] |
The projects to leave out: 'hidden', 'removed', or both |
orderby |
string | 'date_c' |
The column to sort by |
order |
string | 'DESC' |
The direction of the sort |
limit |
integer | 30 |
The largest number of projects to return |
page |
integer | 1 |
The page to return, counted from 1, with limit projects to a page |
groups |
boolean | false |
Whether to return each group with its projects in an items key, beside the projects that are in no group |
data |
boolean | true |
Whether each project includes its data, when columns is '*' |
With no argument, find() returns up to 30 projects, the newest first, each with its data. The list includes unpublished projects, popups, and the projects inside groups. It leaves out the projects hidden in the LayerSlider dashboard and the groups themselves.
LayerSlider puts where into the SQL as you write it, without escaping, and doesn’t check that columns holds only column names. Don’t build either option from input that you didn’t write.
The two values of exclude don’t match the dashboard’s words. 'hidden' leaves out unpublished projects: the ones published with the switch in Project Settings › Publish › Status turned off. 'removed' leaves out the projects hidden in the dashboard with the Hide button. An empty array leaves out nothing.
To leave out unpublished projects too, set exclude to [ 'hidden', 'removed' ]. With [ 'hidden' ] alone, the projects hidden in the dashboard come back.
For orderby, use one of the keys listed under Return value, except items. For a descending sort, write order as 'DESC', in capitals: any other value, 'desc' included, sorts in ascending order.
limit can’t be turned off: 0 or a negative number returns an empty array. To get every project, set limit higher than the number of projects on the site, or read one page after another until you have as many projects as count() returns.
A group can hold another group. With groups set to true, the inner group has its own items.
Return value
Each project comes back as an array with these keys:
| Key | What it is |
|---|---|
id |
The project’s ID |
group_id |
The ID of the group that the project is in, or an empty value if it’s in none |
author |
The WordPress user ID of the person who created the project |
name |
The project’s name |
slug |
The project’s slug |
data |
The project’s data |
date_c |
When the project was created, as a Unix timestamp |
date_m |
When the project was last modified, as a Unix timestamp |
schedule_start |
The start of the project’s schedule, as a Unix timestamp, or 0 if no date is set |
schedule_end |
The end of the project’s schedule, as a Unix timestamp, or 0 if no date is set |
flag_popup |
1 for a popup, otherwise 0 |
flag_group |
1 for a group, otherwise 0 |
flag_hidden |
1 for an unpublished project, otherwise 0 |
flag_deleted |
1 for a project hidden in the LayerSlider dashboard, otherwise 0 |
items |
Only on a group, with groups set to true: the projects and groups inside it |
The lookups return data as a PHP array, not as a JSON string, and so does a query with the data option on. On a group, data is NULL.
Numbers and flags can arrive as strings, such as '12' for an ID or '1' for a flag. Cast a value to an integer before you compare it as a number, and test group_id with empty() to tell whether a project is in a group.
The array can hold other keys as well. Rely only on the ones listed here.
When nothing matches, a lookup returns false and a query returns an empty array. Test either result with empty().
LS_Sliders::count()
LS_Sliders::count()count() takes no argument and returns how many projects the most recent query of find() matched, whatever its limit and page. For a list split into pages, that’s the total of all the pages. With groups set to true, count() counts the groups and the projects that are in no group, not the projects inside the groups.
Each new query replaces the count, so call count() right after the query whose total you need.
Examples
The first example gets one project by its slug and prints its name. Change summer-sale to the slug of your own project.
<?php
if ( class_exists( 'LS_Sliders' ) ) {
$project = LS_Sliders::find( 'summer-sale' );
if ( $project ) {
echo esc_html( $project['name'] );
}
}
?>The second example builds a list to choose a project from: up to 100 projects, sorted by name, without the unpublished ones and the ones hidden in the dashboard. It selects only the ID and the name, so the query skips the project data.
<?php
if ( class_exists( 'LS_Sliders' ) ) {
$projects = LS_Sliders::find( [
'columns' => 'id, name',
'exclude' => [ 'hidden', 'removed' ],
'orderby' => 'name',
'order' => 'ASC',
'limit' => 100,
] );
echo '<select name="project">';
foreach ( $projects as $project ) {
printf(
'<option value="%s">%s</option>',
esc_attr( $project['id'] ),
esc_html( $project['name'] )
);
}
echo '</select>';
}
?>The third example prints the second page of projects, 10 to a page, and works out the number of pages from count().
<?php
if ( class_exists( 'LS_Sliders' ) ) {
$per_page = 10;
$page = 2;
$projects = LS_Sliders::find( [
'limit' => $per_page,
'page' => $page,
'data' => false,
] );
$pages = (int) ceil( LS_Sliders::count() / $per_page );
foreach ( $projects as $project ) {
echo esc_html( $project['name'] ) . '<br>';
}
printf( 'Page %d of %d', $page, $pages );
}
?>Replacing lsSliders() and lsSliderById()
lsSliderById() and lsSliders() still work, but both have been deprecated since LayerSlider 6.11.0. Replace a call of either function with the call of find() that returns the same result:
| Old call | Replacement |
|---|---|
lsSliderById( 12 ) |
LS_Sliders::find( 12 ) |
lsSliders() |
LS_Sliders::find( [ 'limit' => 50, 'data' => false ] ) |
lsSliders( 10, false, true ) |
LS_Sliders::find( [ 'limit' => 10, 'order' => 'ASC', 'data' => true ] ) |
For other calls of lsSliders(), the first argument is limit. The second sets order to 'DESC' when it’s true and to 'ASC' otherwise. The third sets data to true when it’s true and to false otherwise.
The deprecation notice names a file of LayerSlider, not the file that made the call. To find the call, search your theme and your plugins for the function’s name.