README

A Charcoal service provider embed property.

Table of Contents

• Installation
  • Dependencies
• Service Provider
  • Parameters
  • Services
• 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-embed

Dependencies

Required

• PHP 5.6+: PHP 7 is recommended.
• locomotivemtl/charcoal-property : ^0.8
• guzzlehttp/guzzle : ^6.0 or ^7.0
• embed/embed : ^3.4.10

Service Provider

The following services are provided with the use of locomotivemtl/charcoal-contrib-embed

Services

• embed/repository instance of Embed\EmbedRepository
  • Charcoal\Embed\Mixin\EmbedRepositoryTrait provided for ease of use.

Configuration

Include the embed module in the projects's config file. This will provide everything needed for locomotivemtl/charcoal-contrib-embed to work properly. No need for metadata/views/action/routes path etc.

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

You can provide additional configurations in the project's config file like so :

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

This is the actual default config.

Usage

The Embed Contrib provides a custom Property type : "embed". When using it, the property will fetch embed data from media providers and store them in a third table.

{
    "video": {
        "type": "embed",
        "l10n": true,
        "label": {
            "en": "Video",
            "fr": "Video"
        },
        "notes": "Full video url. ex.: https://www.youtube.com/watch?v=_VIDEO_ID"
    }
}

To load the embed data from database, use EmbedRepository service method

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

Dependency injection :

use EmbedRepositoryTrait;

/**
 * Inject dependencies from a DI Container.
 *
 * @param  Container $container A dependencies container instance.
 * @return void
 */
protected function setDependencies(Container $container)
{
    parent::setDependencies($container);
    $this->setEmbedRepository($container['embed/repository']);
}

Development

To install the development environment:

$ composer install

To run the scripts (phplint, phpcs, and phpunit):

$ composer test

API Documentation

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

Development Dependencies

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

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.

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.