Charcoal Search

A Charcoal service provider my cool feature.

Table of Contents

• Installation
  • Dependencies
• Configuration
• Usage
• Development
  • API Documentation
  • Development Dependencies
  • Coding Style
• Credits
• License

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-contrib-search

Dependencies

Required

• PHP 5.6+: PHP 7 is recommended.
• guzzlehttp/guzzle: 6 or 7
• charcoal-admin: >=0.14
• charcoal-contrib-sitemap: >=0.1.5

Configuration

In your project's config file, require the search module :

{
    "modules": {
        "charcoal/search/search": {}
    }
}

Usage

The module adds a search route action using GET. You may access http://project-url.com/search?keyword=[keyword]. You won't get any results until you run the IndexContent Script.

Before running the script, you need to setup

// Once a day at midnight
// You need to precise the base URL as it won'T be provided by the cli
0 0 * * * cd /[project]/web && /usr/local/bin/php /[project]/web/vendor/bin/charcoal admin/search/index-content -u http://project-url.com/

Each object of the sitemap to index must include data.id and data.objType to be indexable:

{
    "sitemap": {
        "xml": {
            "l10n": true,
            "check_active_routes": true,
            "relative_urls": false,
            "objects": {…}
        },
        "searchables": {
            "l10n": true,
            "check_active_routes": true,
            "relative_urls": false,
            "transformer": "charcoal/search/transformer/indexable",
            "objects": {
                "app/object/section": {
                    "filters": {…},
                    "data": {
                        "id": "{{id}}",
                        "objType": "{{objType}}"
                    }
                },
                …
            }
        }
    }
}

Parameters

• -u (--url) Website URL. Necessary as this is run in a cron script.
• -c (--config) Sitemap builder key (Defaults to xml).
• -n (--no_index_class) Class to filter out content from the crawled pages. Defaults to php-no_index.
• -i (--index_element_id) ID of the element to be indexed in the crawled page. Defaults to entire page body.

Development

API Documentation

• The auto-generated phpDocumentor API documentation is available at:
  https://locomotivemtl.github.io/charcoal-contrib-search/docs/master/
• The auto-generated apigen API documentation is available at:
  https://codedoc.pub/locomotivemtl/charcoal-contrib-search/master/

Development Dependencies

• [php-coveralls/php-coveralls][phpcov]
• [phpunit/phpunit][phpunit]
• [squizlabs/php_codesniffer][phpcs]

Coding Style

The charcoal-contrib-search module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• phpcs.xml.dist and .editorconfig for coding standards.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Credits

• Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.