laravel-memcached-plus

Summary

This package is useful for Laravel 5.0 - 5.2. From 5.3 onwards two PRs I submitted to laravel/framework have been merged, therefore the features of this package are available out-the-box with Laravel 5.3 onwards.

Integrating with cloud memcached services such as MemCachier and memcached cloud can require memcached features not available with the built-in Laravel Cache memcached driver from version 5.0 to 5.2.

These include:

SASL authentication
custom options
persistent connections

Adding 3 new configuration items, this package enhances the built-in Laravel 5 Cache memcached driver. Optionally, this package also allows these extra configuration items to be used for memcached Sessions.

Read on for detailed instructions - you may find it useful to reference the demo app at the same time.

Requirements

= PHP 5.4 with ext-memcached
To use SASL it must be compiled with SASL support. This is the default on Heroku

Installation

Available to install as a Composer package on Packagist, all you need to do is:

composer require b3it/laravel-memcached-plus

If your local environment does not meet the requirements you may need to append the ignore-platform-reqs option:

composer require b3it/laravel-memcached-plus --ignore-platform-reqs

Configuration

Once installed you can use this package to enhance the Laravel Cache and Session services.

Providers

This section discusses the Laravel application configuration file app/config.php.

In the providers array you need to replace following built-in Service Providers:

Illuminate\Cache\CacheServiceProvider and
Illuminate\Session\SessionServiceProvider (optional)

A recommended approach is to comment out the built-in providers and append the Service Providers from this package:

'providers' => [
    ...
    //'Illuminate\Cache\CacheServiceProvider',
    ...
    //'Illuminate\Session\SessionServiceProvider',
    ...

    /*
     * Application Service Providers...
     */
     ...

    'B3IT\MemcachedPlus\CacheServiceProvider',
    'B3IT\MemcachedPlus\SessionServiceProvider', // optional
],

The B3IT\MemcachedPlus\SessionServiceProvider is optional. You only need to add this if:

You want to specify a non-default memcached store to use for sessions, default is "memcached", or
You want to use the memcached features provided by this package for sessions

Cache

This section discusses the Laravel cache configuration file config/cache.php.

This package makes the following extra configuration items available for use with a memcached store:

persistent_id - [Memcached::__construct] (http://php.net/manual/en/memcached.construct.php) explains how this is used
sasl - used by Memcached::setSaslAuthData
options - see Memcached::setOptions

These may be used in a store config like so:

'stores' => [
    'memcachedstorefoo' => [
        'driver'  => 'memcached',
        'persistent_id' => 'laravel',
        'sasl'       => [
            env('MEMCACHIER_USERNAME'),
            env('MEMCACHIER_PASSWORD')
        ],
        'options'    => [
            Memcached::OPT_NO_BLOCK         => true,
            Memcached::OPT_AUTO_EJECT_HOSTS => true,
            Memcached::OPT_CONNECT_TIMEOUT  => 2000,
            Memcached::OPT_POLL_TIMEOUT     => 2000,
            Memcached::OPT_RETRY_TIMEOUT    => 2,
        ],
        'servers' => [
            [
                'host' => '127.0.0.1', 'port' => 11211, 'weight' => 100
            ],
        ],
    ],
],

Note that as this package enhances the built-in Laravel 5 memcached Cache driver, the driver string remains memcached.

In case you are unfamiliar with how to use multiple cache stores in Laravel, you would access this store from your application code like so:

$value = Cache::store('memcachedstorefoo')->get('key');

Session

This section discusses the Laravel session configuration file config/session.php.

If you are using memcached sessions you will have set the driver configuration item to 'memcached'.

If you have added the B3IT\MemcachedPlus\SessionServiceProvider as discussed above, the store configuration item is available. This is explained in the following new snippet you can paste into your session configuration file:

    /*
    |--------------------------------------------------------------------------
    | Session Cache Store
    |--------------------------------------------------------------------------
    |
    | When using the "apc" or "memcached" session drivers, you may specify a
    | cache store that should be used for these sessions. This value must
    | correspond with one of the application's configured cache stores.
    |
    */

    'store' => null,

To use the previous memcached 'plus' store example with sessions you would set this as follows:

    'store' => 'memcachedstorefoo',

Breaking changes between v3 and v4

The configuration of Memcached options has been updated to use the Memcached constants rather than the string constant name.

The session.memcached_store variable has been renamed to session.store.