In recent years, Laravel has become one of the most prominent frameworks software engineers use for building their web applications. Similar to the popularity that CodeIgniter enjoyed in its heyday, Laravel has been lauded for its ease-of-use, friendliness to beginners and its adherence to industry standards.
Introduction
One thing though that not a lot of programmers take advantage of is Laravel's component-based system. Since its conversion to composer-powered components, Laravel 4 has become a very modular system, similar to the verbosity of more mature frameworks like Symfony. This is called the Illuminate group of components, which in my opinion, is not the actual framework itself, but is a compilation of libraries that a framework can potentially use. Laravel's actual framework is represented by the Laravel skeleton application (found on the laravel/laravel GitHub repository) that makes use of these components to build a web application.
In this tutorial, we'll be diving into a group of these components, learning how they work, how they're used by the framework, and how we can extend their functionality.
The Session Component
The Laravel Session component handles sessions for the web application. It makes use of a driver-based system called the Laravel Manager, which acts as both a factory and a wrapper for whichever driver is set in the configuration file. As of this writing, the Session component has drivers for:
-
file- a file-based session driver where session data is saved in an encrypted file. -
cookie- a cookie-based session driver where session data is encrypted in the user's cookies. -
database- session data is saved in whichever database is configured for the application. -
apc- session data is saved in APC. -
memcached- session data is saved in Memcached. -
redis- session data is saved in Redis. -
array- session data is saved in a PHP array. Take note that the array session driver does not support persistence and is usually only used in console commands.
Service Providers
Most Laravel users don't realize but a big part of how Laravel works, is within its service providers. They are essentially bootstrap files for each component and they are abstracted enough so users can bootstrap any components, in any way.
A rough explanation of how this works is below:
- The Laravel Application component is initiated. This is the main driver of the whole framework, responsible for handling the HTTP Request, running the service providers, as well as acting as a dependency container for the framework.
- Once a service provider is ran, its
registermethod is called. This allows us to instantiate whichever component we want.- Keep in mind that all service providers have access to the main Laravel application (via
$this->app), which would let service providers push instances of the resolved classes into the dependency container.
- Keep in mind that all service providers have access to the main Laravel application (via
- Once these dependencies are loaded, we should be free to use them by calling on the container, for example, via Laravel's Facade system,
App::make.
Going back to Sessions, let's take a quick look at the SessionServiceProivider:
/**
* Register the session manager instance.
*
* @return void
*/
protected function registerSessionManager()
{
$this->app->bindShared('session', function($app)
{
return new SessionManager($app);
});
}
/**
* Register the session driver instance.
*
* @return void
*/
protected function registerSessionDriver()
{
$this->app->bindShared('session.store', function($app)
{
// First, we will create the session manager which is responsible for the
// creation of the various session drivers when they are needed by the
// application instance, and will resolve them on a lazy load basis.
$manager = $app['session'];
return $manager->driver();
});
}
These two methods are called by the register() function. The first one, registerSessionManager(), is called to initially register the SessionManager. This class extends the Manager that I mentioned on top. The second one, registerSessionDriver() registers a session handler for the manager, based on what we have configured. This eventually calls this method in the Illuminate\Support\Manager class:
/**
* Create a new driver instance.
*
* @param string $driver
* @return mixed
*
* @throws \InvalidArgumentException
*/
protected function createDriver($driver)
{
$method = 'create'.ucfirst($driver).'Driver';
// We'll check to see if a creator method exists for the given driver. If not we
// will check for a custom driver creator, which allows developers to create
// drivers using their own customized driver creator Closure to create it.
if (isset($this->customCreators[$driver]))
{
return $this->callCustomCreator($driver);
}
elseif (method_exists($this, $method))
{
return $this->$method();
}
throw new \InvalidArgumentException("Driver [$driver] not supported.");
}
From here, we can see that based on the name of the driver, from the configuration file, a specific method is called. So, if we have it configured to use the file session handler, it will call this method in the SessionManager class:
/**
* Create an instance of the file session driver.
*
* @return \Illuminate\Session\Store
*/
protected function createFileDriver()
{
return $this->createNativeDriver();
}
/**
* Create an instance of the file session driver.
*
* @return \Illuminate\Session\Store
*/
protected function createNativeDriver()
{
$path = $this->app['config']['session.files'];
return $this->buildSession(new FileSessionHandler($this->app['files'], $path));
}
The driver class is then injected into a Store class, which is responsible for calling the actual session methods. This lets us actually separate the implementation of the SessionHandlerInterface from the SPL into the drivers, the Store class facilitates it.
Creating Our Own Session Handler
Let's create our own Session Handler, a MongoDB Session handler. First off, we'll need to create a MongoSessionHandler inside a newly installed Laravel project instance. (We'll be borrowing heavily from Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler).:
<?php namespace Illuminate\Session;
use Mongo;
use MongoDate;
use MongoBinData;
class MongoSessionHandler implements \SessionHandlerInterface
{
/**
* Mongo db config
*
* @var array
*/
protected $config;
/**
* Mongo db connection
*
* @var \Mongo
*/
protected $connection;
/**
* Mongodb collection
*
* @var \MongoCollection
*/
protected $collection;
/**
* Create a new Mongo driven handler instance.
*
* @param array $config
* - $config['host'] Mongodb host
* - $config['username'] Mongodb username
* - $config['password'] Mongodb password
* - $config['database'] Mongodb database
* - $config['collection'] Mongodb collection
* @return void
*/
public function __construct(array $config)
{
$this->config = $config;
$connection_string = 'mongodb://';
if (!empty($this->config['username']) && !empty($this->config['password'])) {
$connection_string .= "{$this->config['user']}:{$this->config['password']}@";
}
$connection_string .= "{$this->config['host']}";
$this->connection = new Mongo($connection_string);
$this->collection = $this->connection->selectCollection($this->config['database'], $this->config['collection']);
}
/**
* {@inheritDoc}
*/
public function open($savePath, $sessionName)
{
return true;
}
/**
* {@inheritDoc}
*/
public function close()
{
return true;
}
/**
* {@inheritDoc}
*/
public function read($sessionId)
{
$session_data = $this->collection->findOne(array(
'_id' => $sessionId,
));
if (is_null($session_data)) {
return '';
} else {
return $session_data['session_data']->bin;
}
}
/**
* {@inheritDoc}
*/
public function write($sessionId, $data)
{
$this->collection->update(
array(
'_id' => $sessionId
),
array(
'$set' => array(
'session_data' => new MongoBinData($data, MongoBinData::BYTE_ARRAY),
'timestamp' => new MongoDate(),
)
),
array(
'upsert' => true,
'multiple' => false
)
);
}
/**
* {@inheritDoc}
*/
public function destroy($sessionId)
{
$this->collection->remove(array(
'_id' => $sessionId
));
return true;
}
/**
* {@inheritDoc}
*/
public function gc($lifetime)
{
$time = new MongoDate(time() - $lifetime);
$this->collection->remove(array(
'timestamp' => array('$lt' => $time),
));
return true;
}
}
You should save this in the vendor/laravel/framework/src/Illuminate/Session folder. For the purposes of this project, we'll put it here, but ideally this file should be within its own library namespace.
Next, we need to make sure that the Manager class can call this driver. We can do this by utilizing the Manager::extend method. Open vendor/laravel/framework/src/Illuminate/Session/SessionServiceProvider.php and add the following code. Ideally, we should be extending the service provider, but that is outside the scope of this tutorial.
/**
* Setup the Mongo Driver callback
*
* @return void
*/
public function setupMongoDriver()
{
$manager = $this->app['session'];
$manager->extend('mongo', function($app) {
return new MongoSessionHandler(array(
'host' => $app['config']->get('session.mongo.host'),
'username' => $app['config']->get('session.mongo.username'),
'password' => $app['config']->get('session.mongo.password'),
'database' => $app['config']->get('session.mongo.database'),
'collection' => $app['config']->get('session.mongo.collection')
));
});
}
Make sure to update the register() method to call this method:
/**
* Register the service provider.
*
* @return void
*/
public function register()
{
$this->setupDefaultDriver();
$this->registerSessionManager();
$this->setupMongoDriver();
$this->registerSessionDriver();
}
Next, we need to define the Mongo DB configuration. Open app/config/session.php and define the following configuration settings:
/**
* Mongo DB settings
*/
'mongo' => array(
'host' => '127.0.0.1',
'username' => '',
'password' => '',
'database' => 'laravel',
'collection' => 'laravel_session_collection'
)
While we're on this file, we should also update the driver configuration up top:
'driver' => 'mongo'
Now, try and access the main page (usually, localhost/somefolder/public). If this page loads without showing the WHOOPS page, then congratulations, we've successfully created a brand new session driver! Test it out by setting some dummy data on the session, via Session::set() and then echoing it back via Session::get().
The Auth Component
The Laravel Auth component handles user authentication for the framework, as well as password management. What the Laravel component has done here is to create an abstract interpretation of the typical user-management system which is usable in most web applications, which in turn helps the programmer easily implement a login system. Like the Session component, it also makes use of the Laravel Manager. Currently, the Auth component has drivers for:
-
eloquent- this makes use of Laravel's built-in ORM calledEloquent. It also utilizes the pre-madeUser.phpclass inside themodelsfolder. -
database- this uses whichever database connection is configured by default. It makes use of aGenericUserclass for accessing the user data.
Since this follows the same implementation as the Session component, the service provider is very similar to what we've seen on top:
/**
* Register the service provider.
*
* @return void
*/
public function register()
{
$this->app->bindShared('auth', function($app)
{
// Once the authentication service has actually been requested by the developer
// we will set a variable in the application indicating such. This helps us
// know that we need to set any queued cookies in the after event later.
$app['auth.loaded'] = true;
return new AuthManager($app);
});
}
Here, we can see that it basically creates an AuthManager class that wraps around whichever driver we're using, as well as acting as a factory for it. Inside the AuthManager, it again creates the appropriate driver, wrapped around a Guard class, which acts the same way as the Store class from Session.
Creating Our Own Auth Handler
Like before, let's start by creating a MongoUserProvider:
<?php namespace Illuminate\Auth;
use Mongo;
use Illuminate\Hashing\HasherInterface;
class MongoUserProvider implements UserProviderInterface {
/**
* The mongo instance
*
* @param \Mongo
*/
protected $connection;
/**
* The mongo connection instance
*
* @param \MongoConnection
*/
protected $collection;
/**
* The Mongo config array
*
* @var array
*/
protected $config;
/**
* Create a new Mongo user provider.
*
* @param array $config
* - $config['host'] Mongodb host
* - $config['username'] Mongodb username
* - $config['password'] Mongodb password
* - $config['database'] Mongodb database
* - $config['collection'] Mongodb collection
* @return void
*/
public function __construct(array $config)
{
$this->config = $config;
$connection_string = 'mongodb://';
if (!empty($this->config['username']) && !empty($this->config['password'])) {
$connection_string .= "{$this->config['user']}:{$this->config['password']}@";
}
$connection_string .= "{$this->config['host']}";
$this->connection = new Mongo($connection_string);
$this->collection = $this->connection->selectCollection($this->config['database'], $this->config['collection']);
}
/**
* Retrieve a user by their unique identifier.
*
* @param mixed $identifier
* @return \Illuminate\Auth\UserInterface|null
*/
public function retrieveById($identifier)
{
$user_data = $this->collection->findOne(array(
'_id' => $identifier,
));
if (!is_null($user_data)) {
return new GenericUser((array) $user_data);
}
}
/**
* Retrieve a user by the given credentials.
*
* @param array $credentials
* @return \Illuminate\Auth\UserInterface|null
*/
public function retrieveByCredentials(array $credentials)
{
// Attempt to look for the user first regardless of password
// We'll do that in the validateCredentials method
if (isset($credentials['password'])) {
unset($credentials['password']);
}
$user_data = $this->collection->findOne($credentials);
if (!is_null($user_data)) {
return new GenericUser((array) $user_data);
}
}
/**
* Validate a user against the given credentials.
*
* @param \Illuminate\Auth\UserInterface $user
* @param array $credentials
* @return bool
*/
public function validateCredentials(UserInterface $user, array $credentials)
{
if (!isset($credentials['password'])) {
return false;
}
return ($credentials['password'] === $user->getAuthPassword());
}
}
It's important to take note here that I'm not checking against a hashed password, this was done for simplicity's sake to make it easier on our part to create dummy data and test this later. In production code, you need to make sure to hash the password. Check out the Illuminate\Auth\DatabaseUserProvider class for a great example on how to do this.
Afterwards, we need to register our custom driver callback on the AuthManager. To do so, we need to update the service provider's register method:
/**
* Register the service provider.
*
* @return void
*/
public function register()
{
$this->app->bindShared('auth', function($app)
{
// Once the authentication service has actually been requested by the developer
// we will set a variable in the application indicating such. This helps us
// know that we need to set any queued cookies in the after event later.
$app['auth.loaded'] = true;
$auth_manager = new AuthManager($app);
$auth_manager->extend('mongo', function($app) {
return new MongoUserProvider(
array(
'host' => $app['config']->get('auth.mongo.host'),
'username' => $app['config']->get('auth.mongo.username'),
'password' => $app['config']->get('auth.mongo.password'),
'database' => $app['config']->get('auth.mongo.database'),
'collection' => $app['config']->get('auth.mongo.collection')
)
);
});
return $auth_manager;
});
}
Lastly, we also need to update the auth.php configuration file to make use of the Mongo driver, as well as provide it the proper Mongo configuration values:
'driver' => 'mongo',
...
...
...
/**
* Mongo DB settings
*/
'mongo' => array(
'host' => '127.0.0.1',
'username' => '',
'password' => '',
'database' => 'laravel',
'collection' => 'laravel_auth_collection'
)
Testing this is a little trickier, to do so, use the Mongo DB CLI to insert a new user into the collection:
mongo
> use laravel_auth
switched to db laravel_auth
> db.laravel_auth_collection.insert({id: 1, email:"[email protected]", password:"test_password"})
> db.laravel_auth_collection.find()
> { "_id" : ObjectId("530c609f2caac8c3a8e4814f"), "id" 1, "email" : "[email protected]", "password" : "test_password" }
Now, test it out by trying an Auth::validate method call:
var_dump(Auth::validate(array('email' => '[email protected]', 'password' => 'test_password')));
This should dump a bool(true). If it does, then we've successfully created our own Auth driver!
The Cache Component
The Laravel Cache component handles caching mechanisms for use in the framework. Like both of the components that we've discussed, it also makes use of the Laravel Manager (Are you noticing a pattern?). The Cache component has drivers for:
apcmemcachedredis-
file- a file-based cache. Data is saved into theapp/storage/cachepath. -
database- database-based cache. Data is saved into rows into the database. The database schema is described in the Laravel Documentation. -
array- data is "cached" in an array. Keep in mind that thearraycache is not persistent and is cleared on every page load.
Since this follows the same implementation as both components that we've discussed, you can safely assume that the service provider is fairly similar:
/**
* Register the service provider.
*
* @return void
*/
public function register()
{
$this->app->bindShared('cache', function($app)
{
return new CacheManager($app);
});
$this->app->bindShared('cache.store', function($app)
{
return $app['cache']->driver();
});
$this->app->bindShared('memcached.connector', function()
{
return new MemcachedConnector;
});
$this->registerCommands();
}
The register() method here creates a CacheManager, that again acts as a wrapper and factory for the drivers. Within the manager, it wraps the driver around a Repository class, similar to the Store and Guard classes.
Creating Our Own Cache Handler
Create the MongoStore, which should extend the Illuminate\Cache\StoreInterface:
<?php namespace Illuminate\Cache;
use Mongo;
class MongoStore implements StoreInterface
{
/**
* The mongo instance
*
* @param \Mongo
*/
protected $connection;
/**
* The mongo connection instance
*
* @param \MongoConnection
*/
protected $collection;
/**
* The Mongo config array
*
* @var array
*/
protected $config;
/**
* Create a new Mongo cache store.
*
* @param array $config
* - $config['host'] Mongodb host
* - $config['username'] Mongodb username
* - $config['password'] Mongodb password
* - $config['database'] Mongodb database
* - $config['collection'] Mongodb collection
* @return void
*/
public function __construct(array $config)
{
$this->config = $config;
$connection_string = 'mongodb://';
if (!empty($this->config['username']) && !empty($this->config['password'])) {
$connection_string .= "{$this->config['user']}:{$this->config['password']}@";
}
$connection_string .= "{$this->config['host']}";
$this->connection = new Mongo($connection_string);
$this->collection = $this->connection->selectCollection($this->config['database'], $this->config['collection']);
}
/**
* Retrieve an item from the cache by key.
*
* @param string $key
* @return mixed
*/
public function get($key)
{
$cache_data = $this->getObject($key);
if (!$cache_data) {
return null;
}
return unserialize($cache_data['cache_data']);
}
/**
* Return the whole object instead of just the cache_data
*
* @param string $key
* @return array|null
*/
protected function getObject($key)
{
$cache_data = $this->collection->findOne(array(
'key' => $key,
));
if (is_null($cache_data)) {
return null;
}
if (isset($cache_data['expire']) && time() >= $cache_data['expire']) {
$this->forget($key);
return null;
}
return $cache_data;
}
/**
* Store an item in the cache for a given number of minutes.
*
* @param string $key
* @param mixed $value
* @param int $minutes
* @return void
*/
public function put($key, $value, $minutes)
{
$expiry = $this->expiration($minutes);
$this->collection->update(
array(
'key' => $key
),
array(
'$set' => array(
'cache_data' => serialize($value),
'expiry' => $expiry,
'ttl' => ($minutes * 60)
)
),
array(
'upsert' => true,
'multiple' => false
)
);
}
/**
* Increment the value of an item in the cache.
*
* @param string $key
* @param mixed $value
* @return void
*
* @throws \LogicException
*/
public function increment($key, $value = 1)
{
$cache_data = $this->getObject($key);
if (!$cache_data) {
$new_data = array(
'cache_data' => serialize($value),
'expiry' => $this->expiration(0),
'ttl' => $this->expiration(0)
);
} else {
$new_data = array(
'cache_data' => serialize(unserialize($cache_data['cache_data']) + $value),
'expiry' => $this->expiration((int) ($cache_data['ttl']/60)),
'ttl' => $cache_data['ttl']
);
}
$this->collection->update(
array(
'key' => $key
),
array(
'$set' => $new_data
),
array(
'upsert' => true,
'multiple' => false
)
);
}
/**
* Decrement the value of an item in the cache.
*
* @param string $key
* @param mixed $value
* @return void
*
* @throws \LogicException
*/
public function decrement($key, $value = 1)
{
$cache_data = $this->getObject($key);
if (!$cache_data) {
$new_data = array(
'cache_data' => serialize((0 - $value)),
'expiry' => $this->expiration(0),
'ttl' => $this->expiration(0)
);
} else {
$new_data = array(
'cache_data' => serialize(unserialize($cache_data['cache_data']) - $value),
'expiry' => $this->expiration((int) ($cache_data['ttl']/60)),
'ttl' => $cache_data['ttl']
);
}
$this->collection->update(
array(
'key' => $key
),
array(
'$set' => $new_data
),
array(
'upsert' => true,
'multiple' => false
)
);
}
/**
* Store an item in the cache indefinitely.
*
* @param string $key
* @param mixed $value
* @return void
*/
public function forever($key, $value)
{
return $this->put($key, $value, 0);
}
/**
* Remove an item from the cache.
*
* @param string $key
* @return void
*/
public function forget($key)
{
$this->collection->remove(array(
'key' => $key
));
}
/**
* Remove all items from the cache.
*
* @return void
*/
public function flush()
{
$this->collection->remove();
}
/**
* Get the expiration time based on the given minutes.
*
* @param int $minutes
* @return int
*/
protected function expiration($minutes)
{
if ($minutes === 0) return 9999999999;
return time() + ($minutes * 60);
}
/**
* Get the cache key prefix.
*
* @return string
*/
public function getPrefix()
{
return '';
}
}
We'll also need to add the Mongo callback again to the manager:
/**
* Register the service provider.
*
* @return void
*/
public function register()
{
$this->app->bindShared('cache', function($app)
{
$cache_manager = new CacheManager($app);
$cache_manager->extend('mongo', function($app) {
return new MongoStore(
array(
'host' => $app['config']->get('cache.mongo.host'),
'username' => $app['config']->get('cache.mongo.username'),
'password' => $app['config']->get('cache.mongo.password'),
'database' => $app['config']->get('cache.mongo.database'),
'collection' => $app['config']->get('cache.mongo.collection')
)
);
});
return $cache_manager;
});
$this->app->bindShared('cache.store', function($app)
{
return $app['cache']->driver();
});
$this->app->bindShared('memcached.connector', function()
{
return new MemcachedConnector;
});
$this->registerCommands();
}
Lastly, we'll need to update the cache.php config file:
'driver' => 'mongo',
...
...
...
/**
* Mongo DB settings
*/
'mongo' => array(
'host' => '127.0.0.1',
'username' => '',
'password' => '',
'database' => 'laravel',
'collection' => 'laravel_cache_collection'
)
Now, attempt to use the Cache::put() and Cache::get() methods. If done correctly, we should be able to use MongoDB to cache the data!
Conclusion
In this tutorial, we learned about the following:
- Laravel's component-based system called
Illuminate, which is used by the Laravel framework. - Laravel Service Providers and a little bit about how they work.
- Laravel's Manager system, which acts as both a wrapper and factory for the drivers.
- Session, Auth and Cache components and how to create new drivers for each.
- Store, Guard and Repository libraries which utilize these drivers.
Hopefully this helps programmers create their own drivers and extend the current functionality of the Laravel framework.
Comments