Быстрый старт

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

Введение

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

Чтобы рассмотреть основной набор функций Laravel, мы создадим простой список задач и будем придерживаться его (типичный пример списка «to-do»). Полный финальный вариант исходного кода для этого проекта доступен на GitHub.

Установка

Установка Laravel

Конечно, в первую очередь вам будет нужен свежий фреймворк Laravel. Чтобы запустить его, вы можете использовать виртуальную машину Homestead или локальную PHP-среду на ваш выбор. Как только ваше окружение будет готово, вы можете установить фреймворк Laravel, используя Composer:

shcomposer create-project laravel/laravel quickstart --prefer-dist

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

Вы можете просто прочитать данное руководство. Однако, если вы хотите загрузить исходный код для этого руководства и выполнить его на локальной машине, то можете клонировать Git хранилище и установить зависимости:

shgit clone https://github.com/laravel/quickstart-basic quickstart
cd quickstart
composer install
php artisan migrate

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

Подготовка базы данных

Миграции БД

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

Итак, давайте создадим таблицу БД, которая будет содержать все наши задачи. Для создания различных классов может быть использован интерфейс Artisan. Он избавит вас от ручной генерации кода при создании проектов Laravel. Поэтому давайте используем команду shmake:migration для создания миграции новой базы данных для нашей таблицы tasks:

shphp artisan make:migration create_tasks_table --create=tasks

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

<?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 shmigrate. Если вы используете Homestead, вы должны выполнить эту команду в своей виртуальной машине, так как у вашей host-машины не будет прямого доступа к базе данных:

shphp artisan migrate

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

Модели Eloquent

Eloquent — это стандартное ORM для Laravel (объектно-реляционное отображение). Eloquent делает безболезненным получение и хранение данных в вашей базе данных, используя чётко определённые «модели». Обычно, каждая Eloquent модель однозначно соответствует одной таблице базы данных.

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

shphp artisan make:model Task

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

<?php

  namespace App;

  use Illuminate\Database\Eloquent\Model;

  class Task extends Model
  {
    //
  }

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

Маршрутизация

Заглушки маршрутов

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

Для нашего приложения нам будут нужны по крайней мере три маршрута: маршрут для вывода на экран списка всех наших задач, маршрут для добавления новых задач и маршрут для удаления существующих задач. Давайте напишем заглушки для всех этих маршрутов в файле app/Http/routes.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) {
    //
  });

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

Вывод представления

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

В Laravel все HTML-шаблоны хранятся в каталоге resources/views, и мы можем использовать вспомогательную функцию PHPview(), чтобы возвратить один из этих шаблонов по нашему маршруту:

Route::get('/', function () {
  return view('tasks');
});

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

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

Создание макетов и представлений

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

Определяем макет

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

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

Наше представление app.blade.php должно выглядеть примерно так:

xml  <!-- 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>

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

Определяем дочернее представление

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

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

  <!-- 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

Несколько разъясняющих замечаний

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

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

Итак, мы определили основной макет и представление для нашего приложения. Помните, мы возвращаем это представление по маршруту /:

Route::get('/', function () {
  return view('tasks');
});

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

Добавление задач

Проверка ввода

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

Для этой формы мы создадим обязательное поле name и зададим, что оно должно содержать не более 255 символов. Если проверка не пройдёт, то мы перенаправим пользователя назад к URL /, а также возвратим ему в сессию его введённые данные с указанием на ошибки. Возврат введённых данных в сессию позволит нам сохранить их, даже если в них будут ошибки:

Route::post('/task', function (Request $request) {
  $validator = Validator::make($request->all(), [
    'name' => 'required|max:255',
  ]);

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

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

Переменная PHP$errors

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

Помните, что мы использовали директиву PHP@include('common.errors') в нашем представлении, чтобы отобразить ошибки ввода формы. PHPcommon.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

Переменная PHP$errors доступна в любом представлении Laravel. Если не будет ошибок ввода, она просто будет пустым экземпляром PHPViewErrorBag.

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

Теперь, когда обрабатывается ввод данных, давайте создадим новую задачу, продолжая заполнять наш маршрут. Как только новая задача была создана, мы перенаправим пользователя назад к URL /. Чтобы создать задачу, мы можем использовать метод PHPsave() после создания и установки свойств для новой модели 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('/');
});

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

Отображение существующих задач

Во-первых, мы должны отредактировать наш маршрут /, чтобы передать все существующие задачи в представление. Функция PHPview() принимает массив данных вторым параметром, который будет доступным для представления. Каждый ключ массива станет переменной в представлении:

Route::get('/', function () {
  $tasks = Task::orderBy('created_at', 'asc')->get();

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

Когда данные переданы, мы можем обращаться к задачам в нашем представлении tasks.blade.php и выводить их на экран таблицей. Blade-конструкция PHP@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» в коде, где предположительно будет находиться наша кнопка. Давайте добавим кнопку удаления к каждой строке нашего списка задач в представлении tasks.blade.php. Мы создадим маленькую однокнопочную форму для каждой задачи в списке. После нажатия кнопки приложению будет отправляться запрос 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>

Примечание по спуфингу метода

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

Мы можем имитировать запрос DELETE, выводя результаты функции PHPmethod_field('DELETE') в нашей форме. Эта функция генерирует скрытый ввод формы, который распознается Laravel и используется, чтобы переопределить вызываемый метод HTTP. Сгенерированное поле будет похоже на это:

<input type="hidden" name="_method" value="DELETE">

Удаление задачи

Наконец, давайте добавим к нашему маршруту логику удаления текущей задачи. Мы можем использовать неявную привязку модели, чтобы автоматически получить модель Task, которая соответствует параметру маршрута {task}.

В обратном вызове нашего маршрута мы используем метод PHPdelete() для удаления записи. Как только запись удалена, мы перенаправим пользователя назад к URL /:

Route::delete('/task/{task}', function (Task $task) {
  $task->delete();

  return redirect('/');
});