first

Author: taylorotwell

authentication.md

@@ -0,0 +1,117 @@
+# Authentication
+
+- [Introduction](#introduction)
+- [Configuration](#configuration)
+- [Basic Usage](#basic-usage)
+
+<a name="introduction"></a>
+## Introduction
+
+Lumen is primarily designed for building fast micro-services and APIs; however, if you wish, you may use Laravel's authentication system to authenticate users of your Lumen application.
+
+<a name="configuration"></a>
+## Configuration
+
+> **Note:** Using the authentication system will require enabling sessions. You can do so by uncommenting the middleware listed in the default call to `$app->middleware` in your `bootstrap/app.php` file.
+
+The authentication system has several configuration options you can set in your `.env` file:
+
+- `AUTH_DRIVER`
+- `AUTH_MODEL`
+- `AUTH_TABLE`
+
+The `AUTH_DRIVER` value specifies the authentication driver used by the framework. If `eloquent` is specified as the driver, the Eloquent ORM driver will be utilized, while `database` will specify that the plain "database" driver should be used.
+
+The `AUTH_MODEL` option specifies the name of the Eloquent model to be used for authentication. This model must implement the `Illuminate\Contracts\Auth\Authenticatable` contract. For an example model, check out the `App\User` model included in the full-stack Laravel framework.
+
+The `AUTH_TABLE` option specifies which databse table contains the "users" of your application. Of course, this option only applies when using the `database` authentication driver.
+
+<a name="basic-usage"></a>
+## Basic Usage
+
+Unlike Laravel, Lumen does not include any scaffolding for authentication, so you will need to use the authentication libraries manually.
+
+> **Note:** If you intend to use the `Auth` facade, be sure to uncomment the `$app->withFacades()` call in your `bootstrap/app.php` file.
+
+First, let's check out the `attempt` method:
+
+	use Illuminate\Http\Request;
+
+	$app->post('auth/login', function(Request $request) {
+
+		if (Auth::attempt($request->only('email', 'password'))) {
+			return redirect('dashboard');
+		}
+
+	});
+
+The `attempt` method accepts an array of key / value pairs as its first argument. The `password` value will be [hashed](/docs/hashing). The other values in the array will be used to find the user in your database table. So, in the example above, the user will be retrieved by the value of the `email` column. If the user is found, the hashed password stored in the database will be compared with the hashed `password` value passed to the method via the array. If the two hashed passwords match, a new authenticated session will be started for the user.
+
+The `attempt` method will return `true` if authentication was successful. Otherwise, `false` will be returned.
+
+> **Note:** In this example, `email` is not a required option, it is merely used as an example. You should use whatever column name corresponds to a "username" in your database.
+
+#### Authenticating A User With Conditions
+
+You also may add extra conditions to the authentication query:
+
+	if (Auth::attempt(['email' => $email, 'password' => $password, 'active' => 1]))	{
+		// The user is active, not suspended, and exists.
+	}
+
+#### Determining If A User Is Authenticated
+
+To determine if the user is already logged into your application, you may use the `check` method:
+
+	if (Auth::check()) {
+		// The user is logged in...
+	}
+
+#### Authenticating A User And "Remembering" Them
+
+If you would like to provide "remember me" functionality in your application, you may pass a boolean value as the second argument to the `attempt` method, which will keep the user authenticated indefinitely, or until they manually logout. Of course, your `users` table must include the string `remember_token` column, which will be used to store the "remember me" token.
+
+	if (Auth::attempt(['email' => $email, 'password' => $password], $remember)) {
+		// The user is being remembered...
+	}
+
+If you are "remembering" users, you may use the `viaRemember` method to determine if the user was authenticated using the "remember me" cookie:
+
+	if (Auth::viaRemember()) {
+		//
+	}
+
+#### Authenticating Users By ID
+
+To log a user into the application by their ID, use the `loginUsingId` method:
+
+	Auth::loginUsingId(1);
+
+#### Validating User Credentials Without Login
+
+The `validate` method allows you to validate a user's credentials without actually logging them into the application:
+
+	if (Auth::validate($credentials)) {
+		//
+	}
+
+#### Logging A User In For A Single Request
+
+You may also use the `once` method to log a user into the application for a single request. No sessions or cookies will be utilized:
+
+	if (Auth::once($credentials)) {
+		//
+	}
+
+#### Manually Logging In A User
+
+If you need to log an existing user instance into your application, you may call the `login` method with the user instance:
+
+	Auth::login($user);
+
+This is equivalent to logging in a user via credentials using the `attempt` method.
+
+#### Logging A User Out Of The Application
+
+	Auth::logout();
+

cache.md

@@ -0,0 +1,98 @@
+# Cache
+
+- [Configuration](#configuration)
+- [Basic Usage](#basic-usage)
+
+<a name="configuration"></a>
+## Configuration
+
+The `CACHE_DRIVER` option in your `.env` file determines the cache "driver" to be used for the application. Of course, Lumen supports the same drivers as the full-stack Laravel framework, including Memcached and Redis:
+
+- `array`
+- `file`
+- `memcached`
+- `redis`
+- `database`
+
+### Memcached
+
+If you are using the Memcached driver, you may also set the `MEMCACHED_HOST` and `MEMCACHED_PORT` options in your `.env` configuration file.
+
+### Redis
+
+Before using a Redis cache with Laravel, you will need to install the `predis/predis` package (~1.0) via Composer.
+
+### Database
+
+When using the database cache driver, you will need to setup a table to contain the cache items. You'll find an example Schema declaration for the table below:
+
+	Schema::create('cache', function($table) {
+	    $table->string('key')->unique();
+	    $table->text('value');
+	    $table->integer('expiration');
+	});
+
+<a name="basic-usage"></a>
+## Basic Usage
+
+> **Note:** If you intend to use the `Cache` facade, be sure to uncomment the `$app->withFacades()` call in your `bootstrap/app.php` file.
+
+#### Storing An Item In The Cache
+
+	Cache::put('key', 'value', $minutes);
+
+#### Using Carbon Objects To Set Expire Time
+
+	$expiresAt = Carbon::now()->addMinutes(10);
+
+	Cache::put('key', 'value', $expiresAt);
+
+#### Storing An Item In The Cache If It Doesn't Exist
+
+	Cache::add('key', 'value', $minutes);
+
+The `add` method will return `true` if the item is actually **added** to the cache. Otherwise, the method will return `false`.
+
+#### Checking For Existence In Cache
+
+	if (Cache::has('key')) {
+		//
+	}
+
+#### Retrieving An Item From The Cache
+
+	$value = Cache::get('key');
+
+#### Retrieving An Item Or Returning A Default Value
+
+	$value = Cache::get('key', 'default');
+
+	$value = Cache::get('key', function() { return 'default'; });
+
+#### Storing An Item In The Cache Permanently
+
+	Cache::forever('key', 'value');
+
+Sometimes you may wish to retrieve an item from the cache, but also store a default value if the requested item doesn't exist. You may do this using the `Cache::remember` method:
+
+	$value = Cache::remember('users', $minutes, function() {
+		return DB::table('users')->get();
+	});
+
+You may also combine the `remember` and `forever` methods:
+
+	$value = Cache::rememberForever('users', function() {
+		return DB::table('users')->get();
+	});
+
+Note that all items stored in the cache are serialized, so you are free to store any type of data.
+
+#### Pulling An Item From The Cache
+
+If you need to retrieve an item from the cache and then delete it, you may use the `pull` method:
+
+	$value = Cache::pull('key');
+
+#### Removing An Item From The Cache
+
+	Cache::forget('key');

configuration.md

@@ -0,0 +1,73 @@
+# Configuration
+
+- [Introduction](#introduction)
+- [After Installation](#after-installation)
+- [Configuration Files](#configuration-files)
+- [Pretty URLs](#pretty-urls)
+
+<a name="introduction"></a>
+## Introduction
+
+Unlike Laravel, Lumen only uses a single `.env` configuration file which can be used to configure the various aspects of the framework. The `.env.example` that ships with the framework can be used as a starting-point for your Lumen configuration.
+
+If you would like to use the `vlucas/phpdotenv` library to load your environment variables into the `$_ENV` PHP super-global, you should uncomment the call to `Dotenv::load` in your `bootstrap/app.php` file.
+
+<a name="after-installation"></a>
+## After Installation
+
+Lumen needs very little configuration out of the box. However, you should set your `APP_KEY` configuration option in the `.env` file. This value should be a 32 character, random string.
+
+However, you may also want to configure a few additional components of Laravel, such as:
+
+- [Cache](/docs/cache#configuration)
+- [Database](/docs/database#configuration)
+- [Queue](/docs/queues#configuration)
+- [Session](/docs/session#configuration)
+
+> **Note:** You should never have the `APP_DEBUG` configuration option set to `true` for a production application.
+
+<a name="permissions"></a>
+### Permissions
+
+Laravel may require some permissions to be configured: folders within `storage` and the `bootstrap/cache` directory require write access by the web server.
+
+<a name="configuration-files"></a>
+## Configuration Files
+
+By default, Lumen uses a single `.env` file to configure your application. However, you may use full, "Laravel style" configuration files if you wish. The default configuration files are stored in `vendor/laravel/lumen/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 in `config/options.php`, you can load the file like so:
+
+	$app->configure('options');
+
+<a name="pretty-urls"></a>
+## 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 Laravel application, be sure to enable the `mod_rewrite` module.
+
+If the `.htaccess` file that ships with Laravel 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]
+
+If your web host doesn't allow the `FollowSymlinks` option, try replacing it with `Options +SymLinksIfOwnerMatch`.
+
+### 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](/docs/master/homestead), pretty URLs will be configured automatically.