Installation
Installation
Server Requirements
The Lumen framework has a few system requirements. Of course, all of these requirements are satisfied by the Laravel Homestead virtual machine:
- PHP >= 5.5.9
- OpenSSL PHP Extension
- Mbstring PHP Extension
- Tokenizer PHP Extension
Installing Lumen
Lumen utilizes Composer to manage its dependencies. So, before using Lumen, make sure you have Composer installed on your machine.
Via Lumen Installer
First, download the Lumen installer using Composer:
composer global require "laravel/lumen-installer=~1.0"
Make sure to place the ~/.composer/vendor/bin
directory in your PATH so the lumen
executable can be located by your system.
Once installed, the simple lumen new
command will create a fresh Lumen installation in the directory you specify. For instance, lumen new blog
will create a directory named blog
containing a fresh Lumen installation with all of Lumen's dependencies already installed. This method of installation is much faster than installing via Composer:
lumen new blog
Via Composer Create-Project
You may also install Lumen by issuing the Composer create-project
command in your terminal:
composer create-project laravel/lumen blog "5.1.*"
Configuration
Basic Configuration
Unlike the full-stack Laravel framework which has multiple configuration files, all of the configuration options for the Lumen framework are stored in a single .env
configuration file.
Directory Permissions
After installing Lumen, you may need to configure some permissions. Directories within the storage
directory should be writable by your web server or Lumen will not run. If you are using the Homestead virtual machine, these permissions should already be set.
Application Key
After installing Lumen, you should set your application key to a 32 character, random string. The key can be set in the .env
environment file. If you have not renamed the .env.example
file to .env
, you should do that now. If the application key is not set, your user sessions and other encrypted data will not be secure!
Note: In order for your configuration values to be loaded, you will need to uncomment the
Dotenv::load()
method call in yourbootstrap/app.php
file.
Additional Configuration
Lumen needs almost no other configuration out of the box. You are free to get started developing!
You may also want to configure a few additional components of Lumen, such as:
Pretty URLs
Apache
The framework ships with a public/.htaccess
file that is used to allow URLs without index.php
. If you use Apache to serve your Lumen application, be sure to enable the mod_rewrite
module.
If the .htaccess
file that ships with Lumen does not work with your Apache installation, try this one:
Options +FollowSymLinks
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]
Nginx
On Nginx, the following directive in your site configuration will allow "pretty" URLs:
location / {
try_files $uri $uri/ /index.php?$query_string;
}
Of course, when using Homestead, pretty URLs will be configured automatically.
Environment Configuration
It is often helpful to have different configuration values based on the environment the application is running in. For example, you may wish to use a different cache driver locally than you do on your production server. It's easy using environment based configuration.
To make this a cinch, Lumen utilizes the DotEnv PHP library by Vance Lucas. In a fresh Lumen installation, the root directory of your application will contain a .env.example
file. If you install Lumen via Composer, this file will automatically be renamed to .env
. Otherwise, you should rename the file manually.
All of the variables listed in this file will be loaded into the $_ENV
PHP super-global when your application receives a request. You may use the env
helper to retrieve values from these variables. In fact, if you review the Lumen configuration files, you will notice several of the options already using this helper!
Feel free to modify your environment variables as needed for your own local server, as well as your production environment. However, your .env
file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration.
If you are developing with a team, you may wish to continue including a .env.example
file with your application. By putting place-holder values in the example configuration file, other developers on your team can clearly see which environment variables are needed to run your application.
Configuration Files
You may use full "Laravel style" configuration files if you wish. The default files are stored in the vendor/laravel/lumen-framework/config
directory. Lumen will use your copy of the configuration file if you copy and paste one of the files into a config
directory within your project root.
Using full configuration files will give you more control over some aspects of Lumen's configuration, such as configuring multiple storage "disks" or read / write database connections.
Custom Configuration Files
You may also create your own custom configuration files and load them using the $app->configure()
method. For example, if your configuration file is located at config/options.php
, you can load the file like so:
$app->configure('options');
Accessing The Current Application Environment
You may access the current application environment via the environment
method on the App
facade:
$environment = App::environment();
You may also pass arguments to the environment
method to check if the environment matches a given value. You may even pass multiple values if necessary:
if (App::environment('local')) {
// The environment is local
}
if (App::environment('local', 'staging')) {
// The environment is either local OR staging...
}
An application instance may also be accessed via the app
helper method:
$environment = app()->environment();
Accessing Configuration Values
You may easily access your configuration values using the global config
helper function. The configuration values may be accessed using "dot" syntax, which includes the name of the file and option you with to access. A default value may also be specified and will be returned if the configuration option does not exist:
$value = config('app.timezone');
To set configuration values at runtime, pass an array to the config
helper:
config(['app.timezone' => 'America/Chicago']);