Category search class

Phproberto\Joomla\Entity\Categories\Search\CategorySearch

Allows to easily search categories.

Index

Usage

To start using the category searcher you have to load the phproberto_library and add the use statement like:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Start searching!
$searcher = new CategorySearch(['filter.language' => 'es-ES', 'list.limit' => 5]);
$categories = $searcher->search();

// You can do it in one line!
$categories = CategorySearch::instance(['filter.language' => 'es-ES', 'list.limit' => 5])->search();

Filters

Filters are ways to fine tune your search to retrieve exactly the data that you want.

filter.access

Allows to search categories only available for specific view levels.

Expected Value:

  • integer: Single View level identifier.
  • integer[]: Array of view levels identifiers.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Search only visible categories for Public view level (id: 1)
$categories = CategorySearch::instance(['filter.access' => 1]);

// Search only visible categories for Public or Registered view levels
$categories = CategorySearch::instance(['filter.access' => [1, 2]]);

filter.active_language

When this filter is enabled only categories of the active language will be returned.

Expected Value:

  • boolean: True to to enable it.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

$categories = CategorySearch::instance(['filter.active_language' => true]);

filter.active_user_access

When this filter is enabled only categories that have a view level viewable by the active language will be returned. You will usually use this in all your frontend stuff.

Expected Value:

  • boolean: True to to enable it.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

$categories = CategorySearch::instance(['filter.active_user_access' => true]);

filter.ancestor_id

Return only categories with one or more specific ancestors.

Expected Value:

  • integer: Single ancestor identifier.
  • integer[]: Array of ancestor identifiers.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only categories descendant of category with ID 1
$categories = CategorySearch::instance(['filter.ancestor_id' => 1]);

// Return only categories descendant of category with ID 1 or category with ID 2
$categories = CategorySearch::instance(['filter.ancestor_id' => [1, 2]]);

filter.descendant_id

Return only categories with one or more specific descendants.

Expected Value:

  • integer: Single descendant identifier.
  • integer[]: Array of descendant identifiers.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only ancestors of category with ID 11
$categories = CategorySearch::instance(['filter.descendant_id' => 11]);

// Return only ancestors of category with ID 11 or category with ID 12
$categories = CategorySearch::instance(['filter.descendant_id' => [11, 12]]);

filter.extension

Return only categories from one or more specified extensions.

Expected Value:

  • string: Single extension.
  • string[]: Array of extensions.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only categories from com_content
$categories = CategorySearch::instance(['filter.extension' => 'com_content']);

// Return only categories from com_banners or com_content
$categories = CategorySearch::instance(['filter.extension' => ['com_banners', 'com_content']]);

filter.id

Return only categories with one or more specific ids.

Expected Value:

  • integer: Single identifier.
  • integer[]: Array of identifiers.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only category with ID 11
$categories = CategorySearch::instance(['filter.id' => 11]);

// Return only categories with ID 11 or 12
$categories = CategorySearch::instance(['filter.id' => [11, 12]]);

filter.language

Return only categories from one or more specified languages.

Expected Value:

  • string: Single language tag.
  • string[]: Array of language tags.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only categories in english
$categories = CategorySearch::instance(['filter.language' => 'en-GB']);

// Return only categories in english or spanish
$categories = CategorySearch::instance(['filter.language' => ['en-GB', 'es-ES']]);

filter.level

Return only categories with one or more specific levels.

Expected Value:

  • integer: Single level.
  • integer[]: Array of levels.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only category in level 1
$categories = CategorySearch::instance(['filter.level' => 1]);

// Return only category in level 1 or 2
$categories = CategorySearch::instance(['filter.level' => [1, 2]]);

filter.not_id

Return only categories with ids not in the specified list.

Expected Value:

  • integer: Single identifier.
  • integer[]: Array of identifiers.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only categories with ID distinct than 11
$categories = CategorySearch::instance(['filter.not_id' => 11]);

// Return only categories with ID distinct than 11 and distinct than 12
$categories = CategorySearch::instance(['filter.not_id' => [11, 12]]);

filter.parent_id

Return only categories with from one or more parents.

Expected Value:

  • integer: Single parent category identifier.
  • integer[]: Array of parent category identifiers.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only categories that are direct children of category 11
$categories = CategorySearch::instance(['filter.parent_id' => 11]);

// Return only categories that are direct children of category 11 or 12
$categories = CategorySearch::instance(['filter.parent_id' => [11, 12]]);

filter.published

Return only categories in the specifiec status.

Expected Value:

  • integer: Single status identifier.
  • integer[]: Array of status identifiers.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only categories that are published
$categories = CategorySearch::instance(['filter.published' => 1]);

// Return only categories that are in status published or unpublished
$categories = CategorySearch::instance(['filter.published' => [0, 1]]);

filter.search

Return only categories with columns like specified value.

It will search for the string in these columns:

  • title. Category title
  • alias. Category alias
  • path. Full category path
  • extension. Category extension

Expected Value:

  • string: String to search.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

$categories = CategorySearch::instance(['filter.search' => 'My title']);
$categories = CategorySearch::instance(['filter.search' => 'com_content']);
$categories = CategorySearch::instance(['filter.search' => 'my-alias']);
$categories = CategorySearch::instance(['filter.search' => 'parent-alias/my-alias']);

Search modifiers

These modifiers do not filter data but tell the search how many items to return, which order to apply, etc.

list.direction

Tells the search if it has to order items ascendently(ASC) or descendently(DESC).

Expected Value:

  • string: ASC or DESC.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return categories ordered by title in descending order
$categories = CategorySearch::instance(['list.ordering' => 'c.title', 'list.direction' => 'DESC']);

list.limit

Tells the search how many items return.

Expected Value:

  • integer: Number of items.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only 5 categories
$categories = CategorySearch::instance(['list.limit' => 5]);

list.ordering

Tells the search the column that will be used for ordering.

Expected Value:

  • string: Column.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return categories ordered by title in descending order
$categories = CategorySearch::instance(['list.ordering' => 'c.title', 'list.direction' => 'DESC']);

list.start

Tells the search the column that returns values from specific result. It’s usally used for pagination: return 5 items from result 5

Expected Value:

  • integer: First result returned.

Examples:

use Phproberto\Joomla\Entity\Categories\Search\CategorySearch;

// Return only results from 5 to 10
$categories = CategorySearch::instance(['list.start' => 5, 'list.limit' => 5]);