README

A Charcoal service provider for the Embed library.

Installation

The preferred and only supported method is with Composer:

$ composer require locomotivemtl/charcoal-contrib-embed

Dependencies

Required

• PHP v5.6, v7.2 to v7.4, or v8
• locomotivemtl/charcoal-app : v0.8+
• locomotivemtl/charcoal-config : v0.10+
• locomotivemtl/charcoal-property : v0.8+
• guzzlehttp/guzzle : v6 or v7
• guzzlehttp/promises : v1.4 or v2
• embed/embed : v3.4

Service Provider

Services

• embed/repository is an instance of Charcoal\Embed\EmbedRepository and serves as the primary API for fetching and caching embed data.

Configuration

Including the embed module in the projects's configuration file will register the service provider and the [locomotivemtl/charcoal-admin] route for remotely updating the cached embed information:

{
    "modules": {
       "charcoal/embed/embed": {}
    }
}

Otherwise, the service provider can be included directly:

{
    "service_providers": {
        "charcoal/embed/service-provider/embed": {}
    }
}

The contrib package can be configured from the the project's configuration file (default values for illustration):

{
    "embed_config": {
        "ttl": 3600,
        "format": "array",
        "table": "embed_cache"
    }
}

Usage

The contrib package provides a custom embed model property that upon save will fetch the URL's embed information and store a subset of that data in a custom database table.

{
    "video": {
        "type": "embed",
        "l10n": true,
        "label": "Video",
        "notes": "Absolute URL: <code>https://www.youtube.com/watch?v={video_id}</code>"
    }
}

A URL's embed data can be retrieved using the EmbedRepository:

$this->embedRepository()->embedData('https://youtube.com/{video_id}');

Development

The package can be linted with squizlabs/php_codesniffer and tested with phpunit/phpunit from the following command:

$ composer tests

Coding Style

The charcoal-contrib-embed 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.

Credits

• Locomotive

License

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