Установка и настройка Laravel 5.6

10 мая 2018 г.
(обновлено 14 мая 2018 г.)

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

Замечу, что дальнейшее описание актуально для Ubuntu 16.04, хотя в других системах (и даже, возможно, на винде) принципиальных отличий не будет.

Подготовка

Итак, что нужно для установки.

  1. Локальный веб-сервер. В принципе, можно воспользоваться Laravel Homestead (виртуальным образом, содержащим преднастроенную Ubuntu со всем необходимым софтом и уже установленным Laravel). Но это в случае, если вы кроме Laravel больше ничего видеть не хотите. Чаще разработчику приходится иметь дело с множеством фреймворков, CMS и, вообще, всяких-разных технологий, поэтому установленный и настроенный локальный сервер все равно понадобится. Кроме того, использовать виртуальную Ubuntu в Ubuntu... Это уроборос какой-то. В Windows, или даже в Mac, это имеет смысл. Но в нашем случае - не особо. Как установить и настроить сервер на стеке LAMP, описано здесь.
  2. Composer. Сюда.
  3. Собственный инсталлер Laravel-а, который позволит несколько проще создавать проекты на этом фреймворке. Можно и без него, но с ним удобнее.
    composer global require "laravel/installer"

О системных требованиях. PHP >= 7.1.3. Расширения PHP:

OpenSSL

PDO

Mbstring

Tokenizer

XML

Ctype

JSON

Установка

Теперь пришло, наконец, время завести новый проект на Laravel. Идем в корневую директорию веб-сервера (если вы следовали инструкциям из статьи, то это public_html в домашней директории), и отсюда командуем

laravel new super-puper-project

super-puper-project - это название корневой директории нашего проекта, куда и установится Laravel. Естественно, это название - целиком и полностью на ваше усмотрение.

А пока он устанавливается, настроим виртуальный сервер согласно инструкции (прописав в качестве DocumentRoot /home/user/public_html/super-puper-project/public - именно в этой директории в Laravel расположены публичные файлы, доступные веб-серверу, в т.ч. единственная точка входа - файл index.php; выделенное замените своими значениями).

Когда установка фреймворка будет завершена, присвоим нужные права (жирным выделено то, что у вас может отличаться):

chown user:www-data -R super-puper-project
chmod -R 775 super-puper-project/storage
chmod -R 775 super-puper-project/bootstrap/cache

В общем-то, установка на этом закончена. Можно пройти в браузере по ссылке http://super-puper-project (или чего вы там прописали в качестве ServerName в конфиге Апача;  у меня здесь, к примеру, просто laravel) и увидеть такую картину:

Настройка

Конфигурационные файлы расположены в директории config. Их названия говорят сами за себя, так что тут все логично. Каждый файл отдает многомерный массив настроек.

Естественно, мы вольны менять все настройки, как нам заблагорассудится. Но есть один нюанс: если в корне приложения присутствует файл .env (а при установке композером он генерируется автоматически из файла .env.example), то в первую очередь параметры конфигурации берутся из него. Смысл понятен из названия файла (env - сокращение от environment - среда, окружение) - это настройки, характерные для конкретного окружения, т.е. для конкретного сервера, на котором работает этот проект.  Поэтому файл .env числится в .gitignore и в git-репозиторий не попадает. Благодаря библиотеке PHP DotEnv содержимое этого файла парсится в переменные окружения (в суперглобальный массив $_ENV).

Если мы откроем, например, config/app.php (главный конфиг-файл проекта), то заметим, что некоторые переменные заданы через функцию (хелпер) env(). Находится эта функция (как и многие другие (но отнюдь не все!) глобальные функции Laravel-а) в vendor/laravel/framework/src/Illuminate/Support/helpers.php, Именно она проверяет, существет ли соответствующая переменная окружения (переданная первым аргументом), и если существует - то отдает ее, а если нет - значение по умолчанию (переданное вторым аргументом). При этом вторым аргументом может быть и замыкание, оно будет обработано. Т.е. если мы хотим задать какую-нибудь переменную зависимой от окружения - на здоровье: оборачиваем ее в env(), задаем имя и значение по дефолту и прописываем под этим именем в .env. Например, для таймзоны: в config/app.php меняем строку

'timezone' => 'UTC',

на

'timezone' => env('APP_TIMEZONE', 'Europe/Kiev'),

А в .env добавляем строку

APP_TIMEZONE=Europe/Kiev

Теперь при вызове

config('app.timezone')

будем получать 'Europe/Kiev'.

Хелпер config(), позволяет не только получить настройки, но и поменять конфигурацию на лету непосредственно в приложении:

config(['app.timezone' => 'Europe/Kiev');

Функция config(), кстати, вопреки ожиданиям, находится отнюдь не там же, где и env(), а в vendor/laravel/framework/src/Illuminate/Foundation/helpers.php.

Несколько слов об .env. Структура файла простая: каждая строка представляетс собой пару ключ - значение, разделенные знаком =. Если значение содержит пробелы, то должно быть заключено в кавычки; в остальных случаях это необязательно. Значения обрабатываются функцией env() как строки, но есть специальные значения, подверженные преобразованию типов: 'true' и '(true)' преобразуются в булево true, 'false' и '(false)' - в булево false, 'empty' и '(empty)' - в пустую строку, 'null' и '(null)' - в null. Допускается вложенность переменных, т.е. можно сделать, например, так (точно так же, как как в ES6)

APP_NAME=Ку

APP_EXTENDED_NAME=${APP_NAME}-ку!

APP_EXTENDED_NAME теперь содержит строку 'Ку-ку!'

Теперь разберем все конфиг-файлы.

app.php

name - название приложения.

env - окружение. По умолчанию - production. В файле .env - local. В приложении доступно через App::environment(). Передав аргумент (строку или массив; в случае массива проверка происходит по логике ИЛИ), можно проверить требуемое ли окружение:

if (App::environment('local')) {
    // чего-то делаем
}

debug - режим отладки. В .env включен (true).

url - URL приложения. Используется в консоли.

timezone - временная зона. По умолчанию UTC.

locale - язык приложения (сайта). По умолчанию - английский (en).

fallback_locale - резервный язык, на случай если перевод для заданного выше недоступен. По умолчанию - английский (en).

key - ключ, используемый приложением для шифрования. При установке через композер он уже сгенерирован в файле .env.

cipher - метод шифрования, используемый приложением.

providers - массив сервис-провайдеров приложения. Все классы, перечисленные здесь, загружаются автоматичсеки при загрузке приложения и регистрируются как сервис-провайдеры. Чего это такое, и с чем его едят - в статье по ссылке.

aliases - массив псевдонимов (алиасов) классов-фасадов. Из коробки здесь настроен массив всех фасадов, которые есть во фреймворке. Мы вольны добавлять свои.

auth.php. Авторизация.

defaults - настройки по умолчанию. guard (защитник) - используемый по умолчанию guard (по умолчанию - web, настраивается далее в параметре guards). passwords - опции для восстановления пароля (настраиваеются далее в параметре passwords).

guards - настройки конкретных "защитников": web (установленный выше как "защитник" по умолчанию) и api. Для каждого из них, в свою очередь, настраиваются driver (устанавливает, каким образом будет происходить аутентификация; допустимые значения - session и token) и provider (юзер-провайдер; конкретные провайдеры настраиваются далее в параметре providers; по умолчанию users).

providers - юзер-провайдеры. По умолчанию только users, он же прописан для ключа provider в параметре guards. В свою очередь, имеет параметры driver (database или eloquent) и, в зависимости от драйвера, model (для eloquent; название класса модели) или table (для database; таблица базы данных). По умолчанию driver - eloquent и model - App\User::class.

passwords - настройки для восстановления пароля. По умолчанию - толоько users (именно это прописано в настройке passwords параметра defaults). Имеет ключи provider (по умолчанию users; настроен в параметре providers), table (таблица для хранения данных; по умолчанию password_resets) и expire (время жизни токена в базе данных, в минутах; по умолчанию 60).

broadcasting.php

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

default - драйвер по умолчанию. Допустимые значения - pusher, redislognull. Каждый настраивается в параметре connections, По умолчанию - null, т.е. бродкастинг отключен.

connections - настройки всех драйверов. О них - позже, в соответствующем разделе.

cache.php

Настройки кеша.

default - драйвер, используемый для кеширования. По умолчанию - file. Т.е. данные, которые необходимо кешировать, будут записываться в обычные файлы.

stores - конфигурации каждого конкретного драйвера. Суть в том, что можно даже сделать несколько конфигураций для одного и того же драйвера, дав каждой свое название (алиас, ключ этого массива), потому что в default мы прописывам именно алиас, а не сам драйвер. Поддерживаются "apc", "array", "database", "file", "memcached", "redis". Для алиаса file уже прописаны driver file и path - путь к каталогу, где будут храниться файлы кеша (через хелпер storage_path, который прописывает указанный путь внутрь каталога storage) - storage/framework/cache/data.

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

database.php

База данных (сокращенно - БД). Одна из немногих вещей, требующих настройки, т.е. рабочих настроек по умолчанию тут быть не может.

default - тип БД. Замечу, что не PHP-драйвер, а именно тип. Т.е. mysqli писать не надо. Поэтому, увидев mysql, не пугайтесь (воообще забудьте уже о таком драйвере). По умолчанию - mysql.

stores - конфигурация каждого конкретного типа БД. Так же, как и для кеша, можно прописать несколько конфигураций и использовать их в настройке default или файле .env (и вообще в любых настройках, требующих прописать базу данных).

migrations - название таблицы в БД для хранения миграций. Миграции позволяют изменять структуру базы данных во время коллективной разработки запуском одной команды в консоли. Очень удобно. Подробнее рассмотрим позже.

redis - настройки для БД Redis.

filesystems.php

Настройки хранилища файлов, используемого приложением.

default - "диск" по умолчанию. Настраивается в параметре disks. По умолчанию - local.

cloud - "диск" по умолчанию для облачного хранилища (в случае его использования).  Настраивается в параметре disks. По умолчанию - s3.

disks - собственно, диски. "Из коробки" настроены local (прописанный в параметре default), publics3. Для каждого из этих "дисков" доступен параметр driver (допустимые значения: local, ftp, sftp, s3rackspace. Для локальных дисков доступен также параметр root, указывающий корневую категорию диска (для local по умолчанию - storage/app). Для публичного диска (здесь он с ключом public; на публичность указывает ключ visibility со значением public) можно также указать url, по которому хранилище будет доступно извне. root же для public по умолчанию - storage/app/public. Наконец, параметр s3 указывает настройки для облачного хранилища Amazon S3.

hashing.php

Настройки для хеширования паролей.

driver - драйвер. Допустимы bcrypt и argon. По умолчанию - bcrypt

bcrypt - настройки для драйвера, использующего алгоритм Bcrypt. Доступен один параметр - rounds - количество циклов в процессе шифрования: чем больше, тем надежнее хеш, но и дольше процесс. По умолчанию 10.

argon - настройки для драйвера, использующего алгоритм Argon.

logging.php

Настройки логирования.

default - уже привычно: что-то по умолчанию, настраиваемое ниже. В данном случае канал логирования (из channels). По умолчанию - stack.

channels - собственно, всевозможные каналы. Подробнее - в соответствующем разделе.

mail.php

Настройки отправки почты. Так же, как и база данных, практичеcки не имеет рабочих настроек по умолчанию; то, что есть - большей частью только в качестве примера.

driver - допустимы smtp, sendmail, mailgun, mandrill, sessparkpost, log, array. По умолчанию - smtp.

host - хост SMTP-сервера.

port - SMTP порт.

from - глобальные настройки для поля From - отдельно address и name.

encryption - протокол шифрования. По умолчанию - tls.

username и password - соответственно, логин и пароль, требуемые SMTP-сервером (если требуются; по умолчанию и то, и то - null).

sendmail - команда для запуска sendmail. По умолчанию прописано /usr/sbin/sendmail -bs. Для большинства Linux-систем верно.

markdown - настройки для Markdown-рендеринга писем. Подробнее - в соответствующем разделе.

queue.php

Настройки API очередей задач. Поддерживается множество бэкендов через одно API.

default - по умолчанию sync,

connections - настройки конкретных бэкендов. Поддерживаются syncdatabasebeanstalkdsqsredis и null. Подробнее - в соответствующем разделе.

failed - указывает базу данных и таблицу, где будут храниться неудавшиеся задачи. По умолчанию database - mysql (из настроек database) и table - failed_jobs.

services.php

Настройки для сторонних сервисов (Stripe, Mailgun, SparkPost и т.п.). Возвращает массив настроек для всех прописанных сервиов.

session.php

настройки сессий.

driver - драйвер для сессий. Поддерживаются "file", "cookie", "database", "apc", "memcached", "redis", "array". По умолчанию - file.

lifetime - время жизни сессии.

expire_on_close - уничтожать ли сесиию при закрытии браузера. По умолчанию - false, т.е. нет.

encrypt - шифровать ли сесиию. По умолчанию - false, т.е. нет.

files - место хранения файлов сессии при использовании драйвера file. По умолчанию - storage/framework/sessions.

connection - тип базы данных при использовании драйвера database или redis. Должен существовать соответствующий ключ для stores в database.php.

table - таблица базы данных для хранения сессий при использовании драйвера database. По умолчанию - sessions.

store - хранилище для сессий при использовании apc или memcached. Должен существовать соответствующий ключ для stores в cache.php.

lottery - вероятность удаления старых сессий. Некоторые драйверы (database, например) требуют ручной чистки хранилища. Т.е. эта очистка происходит при запросе веб-страницы (index.php). Но делать это при каждом запросе нет смысла (все запросы будут медленными, да и часто устаревших сесссий может вообще не быть при такой частоте), поэтому это делается лишь в определенном количестве запросов, выбранных случайным образом. По умолчанию - в 2-х из 100.

cookie - название cookie для идентификатора сессии. По умолчанию берется из имени приложения, пропущенного через хелпер str_slug.

path - допустимый путь для cookie сессии. Если прописать здесь, например, /bla-bla, то и сессия сможет читаться только для урлов приложения, начинающихся c bla-bla. По умолчанию '/', т.е. сессия доступна для всего приложения.

domain - тоже самое, только для домена. По умолчанию null, т.е. использоваться будет текущий домен.

secure - если true, то куки сессии будут отсылаться только при https. По умолчанию - false.

http_only - если true, то куки сессии доступны лишь по протоколу http (т.е. с Javascript, например, получить к ним доступ не получится). По умолчанию - true.

same_site - определяет поведение cookie сессии при межсайтовом запросе. По умолчанию false, т.е. отключено (потому что включены другие сервисы предотварщения CSRF-атак).

view.php

Настройки путей для представлений (шаблонов).

paths - путь для шаблонов, пропущенный через хелпер resource_path(). По умолчанию - resources/views.

compiled - путь для скомпилированных шаблонизатором Blade файлов. По умолчанию - storage/framework/views.