{{TOC}}

{{DOCVER 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01}}

.(tl_note)
Данная статья документации актуальна только для версий 5.2 и 5.1 и была удалена в версии 5.3.

== Введение ==
Это руководство позволит вам быстро освоить фреймворк Laravel. Оно содержит информацию о миграциях баз данных, Eloquent ORM, маршрутизации, проверке ввода, представлениях и Blade-шаблонах. Это отличная отправная точка для новичков в фреймворке Laravel и PHP-фреймворках в целом. Если вы уже использовали Laravel или другие PHP-фреймворки, вы можете ознакомиться с нашими более продвинутыми руководствами.

Чтобы рассмотреть основной набор функций Laravel, мы создадим простой список задач и будем придерживаться его (типичный пример списка "to-do"). Полный финальный вариант исходного кода для этого проекта ((http://github.com/laravel/quickstart-basic доступен на GitHub)).

== Установка ==
**Установка Laravel**

Конечно, в первую очередь вам будет нужен свежий фреймворк Laravel. Чтобы запустить его, вы можете использовать ((/docs/v5/homestead виртуальную машину Homestead)) или локальную PHP-среду на ваш выбор. Как только ваше окружение будет готово, вы можете установить фреймворк Laravel, используя Composer:
%%(sh)
composer create-project laravel/laravel quickstart --prefer-dist
%%

**Установка проекта Quickstart (не обязательно)**

Вы можете просто прочитать данное руководство. Однако, если вы хотите загрузить исходный код для этого руководства и выполнить его на локальной машине, то можете клонировать Git хранилище и установить зависимости:
%%(sh)
git clone https://github.com/laravel/quickstart-basic quickstart
cd quickstart
composer install
php artisan migrate
%%

Больше информации относительно создания локальной среды разработки Laravel вы сможете найти в документации по ((/docs/v5/homestead Homestead)) и по ((/docs/v5/installation установке)).

== Подготовка базы данных ==
=== Миграции БД ===
Во-первых, давайте использовать миграцию для определения таблицы базы данных для хранения всех наших задач. Миграции БД в Laravel позволяют простым способом определить структуру таблицы базы данных и выполнять модификации с использованием простого и выразительного PHP кода. Вместо того чтобы вручную добавлять столбцы в свои локальные копии БД, ваши товарищи по команде могут просто запустить миграции, которые вы поместили в систему управления версиями.

Итак, давайте создадим таблицу БД, которая будет содержать все наши задачи. Для создания различных классов может быть использован ((/docs/v5/artisan интерфейс Artisan)). Он избавит вас от ручной генерации кода при создании проектов Laravel. Поэтому давайте используем команду %%(sh)make:migration%% для создания миграции новой базы данных для  нашей таблицы %%(t)tasks%%:
%%(sh)
php artisan make:migration create_tasks_table --create=tasks
%%

Миграция будет помещена в каталог %%(t)database/migrations%% вашего проекта. Как вы могли заметить, команда %%(sh)make:migration%% уже добавила автоинкремент ID и метки времени к файлу миграции. Давайте отредактируем этот файл и добавим дополнительный столбец %%(t)string%% для имён наших задач:
%%(php)
<?php

  use Illuminate\Database\Schema\Blueprint;
  use Illuminate\Database\Migrations\Migration;

  class CreateTasksTable extends Migration
  {
    /**
    * Запуск миграций
    *
    * @return void
    */
    public function up()
    {
      Schema::create('tasks', function (Blueprint $table) {
        $table->increments('id');
        $table->string('name');
        $table->timestamps();
      });
    }

    /**
    * Откатить миграции
    *
    * @return void
    */
    public function down()
    {
      Schema::drop('tasks');
    }
  }
%%

Чтобы запустить нашу миграцию, мы будем использовать команду Artisan %%(sh)migrate%%. Если вы используете Homestead, вы должны выполнить эту команду в своей виртуальной машине, так как у вашей host-машины не будет прямого доступа к базе данных:
%%(sh)
php artisan migrate
%%

Эта команда создаст все наши таблицы БД. Если вы просматриваете таблицы БД, используя какой-либо клиент, вы должны заметить новую таблицу %%(t)tasks%%, которая содержит столбцы, определённые в нашей миграции. Теперь мы готовы определить модель Eloquent ORM для наших задач!

== Модели Eloquent ==
((/docs/v5/eloquent Eloquent)) - это стандартное ORM для Laravel (объектно-реляционное отображение). Eloquent делает безболезненным получение и хранение данных в вашей базе данных, используя чётко определённые "модели". Обычно, каждая Eloquent модель однозначно соответствует одной таблице базы данных.

Давайте определим модель %%(t)Task%%, которая будет соответствовать только что созданной нами таблице %%(t)tasks%%. Мы снова можем использовать команду Artisan, чтобы сгенерировать эту модель. В этом случае мы будем использовать команду %%(sh)make:model%%:
%%(sh)
php artisan make:model Task
%%

Модель будет помещена в каталог %%(t)app%% вашего приложения. По умолчанию класс модели пуст. Нам не надо явно указывать, какой таблице соответствует Eloquent модель, потому что подразумевается, что имя таблицы – это имя модели во множественном числе (s на конце). В этом случае модель %%(t)Task%%, как предполагается, соответствует таблице базы данных %%(t)tasks%%. Вот на что должна быть похожа наша пустая модель:
%%(php)
<?php

  namespace App;

  use Illuminate\Database\Eloquent\Model;

  class Task extends Model
  {
    //
  }
%%

Мы ещё познакомимся чуть ближе с моделями Eloquent, когда добавим маршруты к нашему приложению. Разумеется, вы можете заглянуть и в ((/docs/v5/eloquent полную документацию по Eloquent)) для получения дополнительной информации.

== Маршрутизация ==
=== Заглушки маршрутов ===
Теперь можно добавить несколько маршрутов в наше приложение. Маршруты используются для связи URL с контроллерами или анонимными функциями, которые должны быть выполнены, когда пользователь переходит на данную страницу. По умолчанию все маршруты Laravel определены в файле %%(t)app/Http/routes.php%%, который автоматически добавляется в каждый новый проект.

Для нашего приложения нам будут нужны по крайней мере три маршрута: маршрут для вывода на экран списка всех наших задач, маршрут для добавления новых задач и маршрут для удаления существующих задач. Давайте напишем заглушки для всех этих маршрутов в файле %%(t)app/Http/routes.php%%:
%%(php)
<?php

  use App\Task;
  use Illuminate\Http\Request;

  /**
   * Вывести панель с задачами
   */
  Route::get('/', function () {
    //
  });

  /**
   * Добавить новую задачу
   */
  Route::post('/task', function (Request $request) {
    //
  });

  /**
   * Удалить задачу
   */
  Route::delete('/task/{task}', function (Task $task) {
    //
  });
%%

.(alert)
Если в вашей копии Laravel есть %%(t)RouteServiceProvider%%, который уже содержит файл маршрутов по умолчанию в группе посредников %%(t)web%%, то вам не надо вручную добавлять группу в ваш файл %%(t)routes.php%%.

=== Вывод представления ===
Давайте заполним наш маршрут %%(t)/%%. По этому маршруту мы хотим отрисовывать HTML-шаблон, который содержит форму добавления новой задачи, а также список всех текущих задач.

В Laravel все HTML-шаблоны хранятся в каталоге %%(t)resources/views%%, и мы можем использовать вспомогательную функцию %%view()%%, чтобы возвратить один из этих шаблонов по нашему маршруту:
%%(php)
  Route::get('/', function () {
    return view('tasks');
  });
%%

Передача %%(t)tasks%% в функцию %%view()%% создаст экземпляр объекта View, который соответствует шаблону %%(t)resources/views/tasks.blade.php%%.

Конечно, нам необходимо создать это представление, поэтому давайте сделаем это!

== Создание макетов и представлений ==
Наше приложение содержит одно представление с формой добавления новых задач, а также список всех текущих задач. Чтобы помочь вам визуализировать представление, мы сделали скриншот законченного приложения со стандартными стилями Bootstrap CSS:

{{Image /packages/proger/habravel/uploads/374-basic-overview.png}}

=== Определяем макет ===
Почти все веб-приложения используют один макет на всех своих страницах. Например, у нашего приложения есть верхняя панель навигации, которая присутствовала бы на каждой странице (если бы у нас их было больше одной). Laravel упрощает использование этих общих функций на всех страницах, используя **макеты** Blade.

Как мы выяснили ранее, все представления Laravel хранятся в %%(t)resources/views%%. Давайте определим представление нового макета в %%(t)resources/views/layouts/app.blade.php%%. Расширение %%(t).blade.php%% даёт фреймворку команду использовать ((/docs/v5/blade механизм шаблонной обработки Blade)), чтобы отрисовать это представление. Конечно, в Laravel вы можете использовать и простые PHP-шаблоны. Однако Blade позволяет быстро написать простой и небольшой шаблон.

Наше представление %%(t)app.blade.php%% должно выглядеть примерно так:
%%(html)
    <!-- resources/views/layouts/app.blade.php -->

  <!DOCTYPE html>
  <html lang="en">
    <head>
      <title>Laravel Quickstart - Basic</title>

      <!-- CSS и JavaScript -->
    </head>

    <body>
      <div class="container">
        <nav class="navbar navbar-default">
          <!-- Содержимое Navbar -->
        </nav>
      </div>

      @yield('content')
    </body>
  </html>
%%

Обратите внимание на строчку %%(html)@yield('content')%% в макете. Это специальная Blade-директива для указания всем дочерним страницам, наследующим этот шаблон, где они могут внедрить своё содержимое. Давайте определим дочернее представление, которое будет использовать этот макет и выводить его основной контент.

=== Определяем дочернее представление ===
Теперь мы должны определить представление, которое содержит форму создания новой задачи, а также таблицу со списком всех существующих задач. Давайте определим это представление в %%(t)resources/views/tasks.blade.php%%.

Мы пропустим небольшую часть Bootstrap CSS и сфокусируемся на важном. Помните, вы можете скачать весь исходный код этого приложения с ((https://github.com/laravel/quickstart-basic GitHub):
%%(php)
    <!-- resources/views/tasks.blade.php -->

  @extends('layouts.app')

  @section('content')

    <!-- Bootstrap шаблон... -->

    <div class="panel-body">
      <!-- Отображение ошибок проверки ввода -->
      @include('common.errors')

      <!-- Форма новой задачи -->
      <form action="{{ url('task') }}" method="POST" class="form-horizontal">
        {{ csrf_field() }}

        <!-- Имя задачи -->
        <div class="form-group">
          <label for="task" class="col-sm-3 control-label">Задача</label>

          <div class="col-sm-6">
            <input type="text" name="name" id="task-name" class="form-control">
          </div>
        </div>

        <!-- Кнопка добавления задачи -->
        <div class="form-group">
          <div class="col-sm-offset-3 col-sm-6">
            <button type="submit" class="btn btn-default">
              <i class="fa fa-plus"></i> Добавить задачу
            </button>
          </div>
        </div>
      </form>
    </div>

    <!-- TODO: Текущие задачи -->
  @endsection
%%

==== Несколько разъясняющих замечаний ====
Прежде чем двигаться дальше, давайте немного поговорим об этом шаблоне. Во-первых, директива %%@extends%% сообщает Blade, что мы используем макет, который мы определили в %%(t)resources/views/layouts/app.blade.php%%. Все содержимое между %%@section('content')%% и %%@endsection%% будет добавлено вместо строчки директивы %%@yield('content')%% в макете %%(t)app.blade.php%%.

Директива %%@include('common.errors')%% загрузит шаблон %%(t)resources/views/common/errors.blade.php%%. Мы его ещё не определили, но скоро сделаем это!

Итак, мы определили основной макет и представление для нашего приложения. Помните, мы возвращаем это представление по маршруту %%(t)/%%:
%%(php)
  Route::get('/', function () {
    return view('tasks');
  });
%%

Теперь мы готовы добавить код в наш маршрут %%(t)POST /task%%, чтобы обработать входящие данные из формы и добавить новую задачу в БД.

== Добавление задач ==
=== Проверка ввода ===
Теперь, когда у нас есть форма на нашем представлении, мы должны добавить код к нашему маршруту %%(t)POST /task%% в %%(t)app/Http/routes.php%%, чтобы проверить входящие данные из формы и создать новую задачу. Во-первых, давайте проверим ввод.

Для этой формы мы создадим обязательное поле %%(t)name%% и зададим, что оно должно содержать не более %%(t)255%% символов. Если проверка не пройдёт, то мы перенаправим пользователя назад к URL %%(t)/%%, а также возвратим ему в ((/docs/v5/session сессию)) его введённые данные с указанием на ошибки. Возврат введённых данных в сессию позволит нам сохранить их, даже если в них будут ошибки:
%%(php)
  Route::post('/task', function (Request $request) {
    $validator = Validator::make($request->all(), [
      'name' => 'required|max:255',
    ]);

    if ($validator->fails()) {
      return redirect('/')
        ->withInput()
        ->withErrors($validator);
    }

    // Создание задачи...
  });
%%

==== Переменная %%$errors%%====

Давайте сделаем перерыв на минутку, чтобы поговорить о строчке %%->withErrors($validator)%% в нашем примере. Вызов %%->withErrors($validator)%% подсветит в сессии ошибки данного экземпляра проверки ввода, и к ним можно будет обратиться через переменную %%$errors%% в нашем представлении.

Помните, что мы использовали директиву %%@include('common.errors')%% в нашем представлении, чтобы отобразить ошибки ввода формы. %%common.errors%% позволяет нам легко показывать ошибки ввода в одинаковом формате на всех наших страницах. Давайте определим содержимое этого представления:
%%
  <!-- resources/views/common/errors.blade.php -->

  @if (count($errors) > 0)
    <!-- Список ошибок формы -->
    <div class="alert alert-danger">
      <strong>Упс! Что-то пошло не так!</strong>

      <br><br>

      <ul>
        @foreach ($errors->all() as $error)
          <li>{{ $error }}</li>
        @endforeach
      </ul>
    </div>
  @endif
%%

.(alert)
Переменная %%$errors%% доступна в **любом** представлении Laravel. Если не будет ошибок ввода, она просто будет пустым экземпляром %%ViewErrorBag%%.

=== Создание задачи ===

Теперь, когда обрабатывается ввод данных, давайте создадим новую задачу, продолжая заполнять наш маршрут. Как только новая задача была создана, мы перенаправим пользователя назад к URL %%(t)/%%. Чтобы создать задачу, мы можем использовать метод %%save()%% после создания и установки свойств для новой модели Eloquent:
%%
  Route::post('/task', function (Request $request) {
    $validator = Validator::make($request->all(), [
      'name' => 'required|max:255',
    ]);

    if ($validator->fails()) {
      return redirect('/')
        ->withInput()
        ->withErrors($validator);
    }

    $task = new Task;
    $task->name = $request->name;
    $task->save();

    return redirect('/');
  });
%%

Отлично! Теперь мы можем создавать задачи. Давайте продолжим создание нашего представления, добавив список всех существующих задач.

=== Отображение существующих задач ===
Во-первых, мы должны отредактировать наш маршрут %%(t)/%%, чтобы передать все существующие задачи в представление. Функция %%view()%% принимает массив данных вторым параметром, который будет доступным для представления. Каждый ключ массива станет переменной в представлении:
%%
  Route::get('/', function () {
    $tasks = Task::orderBy('created_at', 'asc')->get();

    return view('tasks', [
      'tasks' => $tasks
    ]);
  });
%%

Когда данные переданы, мы можем обращаться к задачам в нашем представлении %%(t)tasks.blade.php%% и выводить их на экран таблицей. Blade-конструкция %%@foreach%% позволяет нам кратко писать циклы, которые компилируются в молниеносный простой PHP-код:
%%
  @extends('layouts.app')

  @section('content')
    <!-- Форма создания задачи... -->

    <!-- Текущие задачи -->
    @if (count($tasks) > 0)
      <div class="panel panel-default">
        <div class="panel-heading">
          Текущая задача
        </div>

        <div class="panel-body">
          <table class="table table-striped task-table">

            <!-- Заголовок таблицы -->
            <thead>
              <th>Task</th>
              <th>&nbsp;</th>
            </thead>

            <!-- Тело таблицы -->
            <tbody>
              @foreach ($tasks as $task)
                <tr>
                  <!-- Имя задачи -->
                  <td class="table-text">
                    <div>{{ $task->name }}</div>
                  </td>

                  <td>
                    <!-- TODO: Кнопка Удалить -->
                  </td>
                </tr>
              @endforeach
            </tbody>
          </table>
        </div>
      </div>
     @endif
  @endsection
%%

Наше приложение почти готово. Но у нас нет способа удалять наши существующие задачи, когда они завершены. Давайте добавим и это!

== Удаление задач ==
=== Добавление кнопки удаления задачи ===
Мы оставили отметку "TODO" в коде, где предположительно будет находиться наша кнопка. Давайте добавим кнопку удаления к каждой строке нашего списка задач в представлении %%(t)tasks.blade.php%%. Мы создадим маленькую однокнопочную форму для каждой задачи в списке. После нажатия кнопки приложению будет отправляться запрос %%(t)DELETE /task%%:
%%
  <tr>
    <!-- Имя задачи -->
     <td class="table-text">
      <div>{{ $task->name }}</div>
    </td>

    <!-- Кнопка Удалить -->
    <td>
      <form action="{{ url('task/'.$task->id) }}" method="POST">
        {{ csrf_field() }}
        {{ method_field('DELETE') }}

        <button type="submit" class="btn btn-danger">
          <i class="fa fa-trash"></i> Удалить
        </button>
      </form>
    </td>
  </tr>
%%

==== Примечание по спуфингу метода ====
Обратите внимание на то, что %%(t)method%% формы кнопки удаления объявлен как %%(t)POST%%, несмотря на то, что мы отвечаем на запрос, используя маршрут %%Route::delete%%. HTML-формы позволяют использовать только %%(t)GET%% и %%(t)POST%% методы HTTP. А нам нужен способ имитировать запрос %%(t)DELETE%% от формы.

Мы можем имитировать запрос %%(t)DELETE%%, выводя результаты функции %%method_field('DELETE')%% в нашей форме. Эта функция генерирует скрытый ввод формы, который распознается Laravel и используется, чтобы переопределить вызываемый метод HTTP. Сгенерированное поле будет похоже на это:
%%
<input type="hidden" name="_method" value="DELETE">
%%

=== Удаление задачи ===
Наконец, давайте добавим к нашему маршруту логику удаления текущей задачи. Мы можем использовать ((//docs/v5/routing#привязка неявную привязку модели)), чтобы автоматически получить модель %%(t)Task%%, которая соответствует параметру маршрута %%(t){task}%%.

В обратном вызове нашего маршрута мы используем метод %%delete()%% для удаления записи. Как только запись удалена, мы перенаправим пользователя назад к URL %%(t)/%%:
%%
  Route::delete('/task/{task}', function (Task $task) {
    $task->delete();

    return redirect('/');
  });
%%