Welcome to our new Help Center. We’re still adding articles, and if you can’t find an answer yet, we’re happy to help.Contact Us

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()

    PHP
    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.

    Warning

    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()

    PHP
    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
    <?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
    <?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
    <?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.