Extensions Manual :: Cartalyst

Preface

Introduction

Extensions give your Laravel application modularity. Think of them as self contained app enclosures, allowing you to manage and maintain portions of your application and separate them from your core architecture.

The package requires PHP 8.0+ and follows the FIG standard PSR-4 to ensure a high level of interoperability between shared PHP code and is fully unit-tested.

Have a read through the Installation Guide and on how to Integrate it with Laravel 9.

Features

Artisan Commands:
- Cache
- Clear Cache
- Enable a single, multiple or all extensions
- Disable a single, multiple or all extensions
- Install a single, multiple or all extensions
- Uninstall a single, multiple or all extensions
- List Extensions
- Migrate Extension
- Migrate Refresh Extension
- Migrate Reset Extension
- Seed Extension
- Autoload Extension
- Clear Extension's autoload
Caching
Events
Deferred Service Providers

Setup

Installation

Cartalyst packages utilize Composer, for more information on how to install Composer please read the Composer Documentation.

Preparation

Open your composer.json file and add the following to the require array:

"cartalyst/extensions": "^7.0"

Add the following lines after the require array on your composer.json file:

"repositories": [
    { "type": "composer", "url": "https://packages.cartalyst.com" }
]

Note: Make sure that after the required changes your composer.json file is valid by running composer validate.

Install the dependencies

Run the composer install or composer update to install or update the new requirement.

Integration

After installing the package, open your Laravel config file which is located at config/app.php and add the following lines.

In the $providers array add the following service provider for this package.

Cartalyst\Extensions\ExtensionsServiceProvider::class,

In the $aliases array add the following facade for this package.

'Extensions' => Cartalyst\Extensions\Facades\Extensions::class,

Migrations

Run the following command to execute the migrations.

php artisan migrate

Configuration

After installing, you can publish the package configuration file into your application by running the following command on your terminal:

php artisan vendor:publish --tag="cartalyst:extensions.config"

This will publish the config file to config/cartalyst/extensions/config.php where you can modify the package configuration.

Autoloading

Extensions are not automatically autoloaded, so you need to ensure that your classes like controllers, models, service providers, repositories and even migrations are autoloaded.

You can autoload your extensions using PSR-4.

For example, add or merge the snippet below to your main composer.json file autoload section:

{
    "autoload": {
        "psr-4": {
            "Foo\\Bar\\": "extensions/foo/bar/"
        }
    }
}

Note: Just modify the path and namespace accordingly to your own extension(s).

Usage

In this section we'll show how you can make use of the extensions package.

Extension Bag

The Extension Bag is a collection that holds your application's extensions. It provides helpers to make interacting with those extensions easy.

The Extension Bag extends the Collection class from Laravel and you can call any of these methods on the Extension Bag.

The Cartalyst\Extensions\Facades\Extensions facade resolves the Extension Bag out of the IoC container.

Additional retrieval methods

Extensions::installed()

Applies a filter to search only the installed extensions.

use Cartalyst\Extensions\Facades\Extensions;

$extensions = Extensions::installed()->get();

// Get the first installed extension
$extension = Extensions::installed()->first();

Extensions::allInstalled()

Returns all the installed extensions.

use Cartalyst\Extensions\Facades\Extensions;

$extensions = Extensions::allInstalled();

Extensions::uninstalled()

Applies a filter to search only the uninstalled extensions.

use Cartalyst\Extensions\Facades\Extensions;

$extensions = Extensions::uninstalled()->get();

// Get the first uninstalled extension
$extension = Extensions::uninstalled()->first();

Extensions::allUninstalled()

Returns all the uninstalled extensions.

use Cartalyst\Extensions\Facades\Extensions;

$extensions = Extensions::allUninstalled();

Extensions::enabled()

Applies a filter to search only the enabled extensions.

use Cartalyst\Extensions\Facades\Extensions;

$extensions = Extensions::enabled()->get();

// Get the first enabled extension
$extension = Extensions::enabled()->first();

Extensions::allEnabled()

Returns all the enabled extensions.

use Cartalyst\Extensions\Facades\Extensions;

$extensions = Extensions::allEnabled();

Extensions::disabled()

Applies a filter to search only the disabled extensions.

use Cartalyst\Extensions\Facades\Extensions;

$extensions = Extensions::disabled()->get();

// Get the first disabled extension
$extension = Extensions::disabled()->first();

Extensions::allDisabled()

Returns all the disabled extensions.

use Cartalyst\Extensions\Facades\Extensions;

$extensions = Extensions::allDisabled();

Extension

Extension Structure

Extensions live under an extensions directory or under the workbench directory by default.

Note: You can update the paths on the configuration to match your requirements.

An extension tree would look like this

extensions
- foo
  - bar
    - extension.php
      
      ...

extension.php

The extension.php file is the kickstarter file and consists of an array that holds information of your extension.

A sample extension.php file might look as follows:

return [

    'slug' => 'foo/bar',

    'version' => '1.0.0',

    'requires' => [
        'bar/baz',
    ],

    'providers' => [
        'Foo\Bar\FooBarServiceProvider',
    ],

    'routes' => function($router) {
        $router->get('foo', 'FooController@index');
    },

];

Every array element is set as an attribute on the extension, it can be retrieved using $extension->{$key}

Required keys

slug
version

Detailed overview

slug

The extension's slug, this is the main identifier for your extensions. A slug should consist of :vendor/:name all in lower case letters.

Example foo/bar

version

The current version of your extension.

requires

An array of dependencies that that adjusts the sort order extensions are retrieved based on. A classic example would be having a base extension that shares common functionality for a set of other extensions. You would require the base extension to ensure the logic is ready to use on any of your other extensions.

Example

'requires' => [

    'bar/baz',

],

After running Extensions::sortExtensions() the current extension is moved below the bar/baz extension to ensure it is not booted before its dependencies.

providers

An array of service provider classes, these are used in a similar fashion to regular service providers. A service provider should contain a register and a boot method that are fired during the application lifecycle.

routes

A closure where routes can be defined, you can simply use the Route facade to register routes as you would in a regular routes file.

Managing extensions

Checks

The methods below allow you to perform several checks on an extension, every method returns a bool.

$extension->isVersioned()

Checks if an extension is versioned.

$extension->isInstalled()

Checks if an extension is installed.

$extension->isUninstalled()

Checks if an extension is uninstalled.

$extension->isEnabled()

Checks if an extension is enabled.

$extension->isDisabled()

Checks if an extension is disabled.

$extension->isBooted()

Checks if an extension is booted.

$extension->canInstall()

Checks if an extension can be installed, extensions might not be installable due to missing dependencies.

$extension->canUninstall()

Checks if an extension can be uninstalled, extensions might not be uninstallable due to being a dependency for another installed extension.

$extension->canEnable()

Checks if an extension can be enabled, extensions might not allow enabling incase a dependency is not enabled.

$extension->canDisable()

Checks if an extension can be disabled, extensions might not allow disabling incase they are a depndency for another enabled extension.

$extension->hasUpdate()

Checks if an extension needs to be updated, this check compares the extension version to the database version.

Actions

$extension->install()

Installs an extension by migrating, seeding and writing the info to the extensions table.

$extension->uninstall()

Uninstall an extension by reverting migrations and deleting the corresponding record from the extensions table.

$extension->enable()

Enables an extension by writing the status to the extensions table.

$extension->disable()

Disables an extension by writing the status to the extensions table.

$extension->update()

Updates an extension by running new migrations and updating the version on the extensions table.

$extension->boot()

Boots an extension, booting an extension happens as follows:

- Registers a regular laravel package.
- Boots providers.
- Registers routes.

Events

There are several events fired throughout the lifecycle of an extension. Every event is receiving the extension object as its argument.

installing

This event is fired prior installing an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.installing', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

installed

This event is fired after installing an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.installed', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

uninstalling

This event is fired prior to uninstalling an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.uninstalling', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

uninstalled

This event is fired after uninstalling an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.uninstalled', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

enabling

This event is fired prior to enabling an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.enabling', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

enabled

This event is fired after enabling an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.enabled', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

disabling

This event is fired prior to disabling an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.disabling', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

disabled

This event is fired after disabling an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.disabled', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

upgrading

This event is fired prior to upgrading an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.upgrading', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

upgraded

This event is fired after upgrading an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.upgraded', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

registering

This event is fired prior to registering an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.registering', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

registered

This event is fired after registering an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.registered', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

booting

This event is fired prior to booting an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.booting', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

booted

This event is fired after booting an extension.

use Illuminate\Support\Facades\Event;
use Cartalyst\Extensions\ExtensionInterface;

Event::listen('extensions.booted', function (ExtensionInterface $extension) {
    // Execute your desired logic.
});

Artisan Commands

Extensions comes with some handy and useful Artisan Commands.

List all available extensions

php artisan extension:list

Options

Option	Description
--sort=	Sorts the results by the given attribute.
--installed	Applies a filter to return only the installed extensions.
--uninstalled	Applies a filter to return only the uninstalled extensions.
--enabled	Applies a filter to return only the installed and enabled extensions.
--disabled	Applies a filter to return only the installed and disabled extensions.

Note: The above options can be chained.

php artisan extension:list --installed --disabled --sort=name

Install Extension(s)

This command will install the given extensions. If no extension(s) are passed, it will install all the extensions.

Install all the extensions

php artisan extension:install

Install the given extensions

php artisan extension:install foo/bar foo/baz

Options

Option	Description
--enable	Flag that indicates that the extension should be enabled after installation.
--seed	Flag that indicates that the database seeder for this extension should be ran after installation.

php artisan extension:install foo/bar --enable

Uninstall Extension(s)

This command will uninstall the given extensions. If no extension(s) are passed, it will uninstall all the extensions.

Uninstall all the extensions

php artisan extension:uninstall

Uninstall the given extensions

php artisan extension:uninstall foo/bar foo/baz

Enable Extension(s)

This command will enable the given extensions. If no extension(s) are passed, it will enable all the extensions.

Enable all the extensions

php artisan extension:enable

Enable the given extensions

php artisan extension:enable foo/bar foo/baz

Disable Extension(s)

This command will disable the given extensions. If no extension(s) are passed, it will disable all the extensions.

Disable all the extensions

php artisan extension:disable

Disable the given extensions

php artisan extension:disable foo/bar foo/baz

Seed Extension(s)

This command will run the database seeder on the given extensions. If no extension(s) are passed, it will seed all the extensions.

Seed all the extensions

php artisan extension:seed

Seed the given extensions

php artisan extension:seed foo/bar foo/baz

Run Migrations of an Extension

This command will run the outstanding migrations on the given extension:

php artisan extension:migrate foo/bar

Rollback Migrations

This command will roll back all of your extension's migrations:

php artisan extension:migrate:reset foo/bar

Rollback & Migrate

This command will roll back all of the extension migrations and then execute the migrate command:

php artisan extension:migrate:refresh foo/bar

Options

Option	Description
--seed	Flag that indicates that the database seeder for this extension should be ran after installation.

php artisan extension:migrate:refresh foo/bar --enable

Cache Extensions

This command will cache the most performant actions when finding and booting extensions:

php artisan extension:cache

Note: If a new extension is added into the filesystem while the cache is enabled, the extension will not be detected until you run the php artisan extension:clear command.

Clear Cached Extensions

This command will clear the cached extensions:

php artisan extension:clear

Hosting

Extensions can be hosted and installed as Composer Packages.

Satis

For more information, refer to Satis Documentation

{
    "repositories": [
        {
            "type": "composer",
            "url": ":satis_url"
        }
    ],
    "require": {
        ":vendor/:package": ":version"
    }
}

VCS

For more information, refer to VCS Documentation

{
    "repositories": [
        {
            "type": "vcs",
            "url": ":git_repository_url"
        }
    ],
    "require": {
        ":vendor/:package": ":version"
    }
}