Php документация: PHP: Руководство по PHP — Manual

Комментирование кода и генерация документации в PHP

Зачем нужны комментарии к программному коду? В каком виде их писать? Где они нужны, а где нет? Как правильно комментировать код? Как придерживаться одинакового стиля документирования всем участникам команды? Какие есть инструменты для генерации документации? В этой статье я постараюсь дать ответы на эти и другие вопросы, а также поделюсь своими мыслями по этому поводу. И поможет мне в этом кролик…

Итак, документация для программы бывает двух видов. Первая — это в самом коде программы в виде комментариев. Второй вариант — используется сторонний инструмент или отдельное место для хранения, например WIKI-движок, в котором описываются концепции работы приложения, примеры использования, взаимодействия между модулями, приводятся разные блок-схемы и диаграммы, в общем, всё то, что нельзя засунуть в код.

Варианты размещения документации

Давайте для начала рассмотрим документацию за пределами кода программы. Хотя это не есть целью данной статьи. В open source проектах нередко встречается практика, когда статьи по документации хранятся в том же репозитории, что и основной код. Например, в библиотеке для генерации фейковых фикстур для PHP документация помещена в README файл; чтоб дочитать до конца, нужно немного поскролить. Популярный HTTP-клиент для PHP Guzzle хранит инструкции по применению в разных файлах в отдельной папке docs. Хранить документацию возле кода — это, конечно, хорошо и удобно. Один раз скачав пакет вендора, у вас есть и код, и документация. Если ваша библиотека небольшая, если она стабильная и не предполагает в будущем постоянных изменений API, которые повлекут за собой постоянное переписывание документации, тогда можете смело размещать документацию в репозитории вашего проекта.

Но всё же всему есть разумный предел. Например, если вы затеяли создание собственного фреймворка, который пишется командой разработчиков, и планируете постоянные релизы, он должен быть полностью задокументирован, более того, документация должна быть переведена на несколько языков, и тогда помещать документацию в репозиторий проекта — не вариант. Потому что для документации характерны постоянные правки, доработки, переводы, исправление опечаток. Это все выливается в большое количество коммитов-фиксов, которые засоряют историю проекта. Навигация по истории коммитов, где изменения кода теряются между изменениями документации, сложна и неудобна. В таком случае лучше создать отдельный репозиторий для документации, например, как это сделали для Symfony. GitHub, GitLab, Bitbucket также предоставляют встроенный инструмент WIKI, его фишкой является то, что он прикреплен к проекту, т.е. не является самостоятельным репозиторием. Но к нему также можно обращаться через Git, т.е. стянуть себе документацию, редактировать её в удобном для себе редакторе, группировать изменения в коммиты и отправлять на сервер, так же и получать свежие правки. Вот пример хорошо оформленной WIKI для библиотеки визуализации D3.js. Конечно, же можно создать сайт для своего продукта и разместить документацию на нем. Но если вы используете какой-либо способ из перечисленных выше, то вы сможете сгенерировать веб-страницы документации из вашего Git или WIKI репозитория, инструменты для этого есть. Если вы любитель комплексных решений, обратите внимание на Confluence от Atlassian. Возможности Confluence вышли далеко за пределы обычного WIKI-движка.

Комментирование кода в коде

Теперь вернемся непосредственно к документированию кода в самом коде. Я пишу эту статью на основании собственного опыта, но после прочтения книги Роберта Мартина «Чистый код», поэтому время от времени будут встречаться умные словечки и цитаты из книги 🙂 . Первый месседж, который пытается донести нам Роберт Мартин, что комментарий — это признак неудачи. Комментарии пишутся для того, чтобы загладить вину программиста, который не смог понятно выразить свою мысль с помощью языка программирования. Процесс написания хорошего и понятного кода — материал достаточно объемный и выходит за рамки этой статьи. Но все же самое простое правило хорошего кода: пишите его так, чтоб он читался как обычные предложения. В объектно-ориентированном программировании все намного проще чем в функциональном, общепринятая практика называть классы именами существительными, а методы — глаголами, делает код более естественным. Например у нас есть кролик, опишем несколько его базовых действий в виде интерфейса:

interface RabbitInterface
{
    public function run();
    public function jump();
    public function stop();
    public function hide();
}

Опустим реализацию этого интерфейса, просто создадим новый объект от класса Rabbit:

$rabbit = new Rabbit();
$rabbit->run();
$rabbit->stop();

Код читается естественно. Метод run заставляет кролика бежать, метод stop также интуитивно понятен, он останавливает текущее действие, и кролик замирает на месте. Теперь давайте немного надрессируем животное и научим его бежать на определенное расстояние, которое будем передавать как параметр в метод run.

$rabbit->run(100);

И кролик побежал… только по коду непонятно, что означает число 100. Это минуты или метры, или сантиметры, или футы? Ситуацию исправил бы комментарий

// Rabbit have to run 100 metres
$rabbit->run(100);

Если кролик начинает «бегать» в вашем коде в нескольких местах, то каждое такое место будет нуждаться в дополнительных комментариях. Комментарии будут дублироваться и их нужно будет поддерживать в нескольких местах одновременно. Первое, что можно сделать, чтоб убрать комментарий — это заменить число на переменную.

$metres = 100;
$rabbit->run($metres);

В таком случае комментарий уже не нужен, так как читабельность чуть-чуть улучшилась, можно увидеть по коду, что кролик пробежит 100 метров. Лучшим же вариантом будет добавить контекст в название метода.

$rabbit->runInMetres(100);

Rabbit — имя существительное, run — глагол, in metres — контекст, который мы добавляем методу, чтобы он передавал суть. Пользуясь такой схемой, можно написать методы

$rabbit->runInSeconds(25);
$rabbit->runTillTime(new \DateTime('tomorrow'));
$rabbit->runTillTheEndOfForest($sherwood);

Они будут передавать суть метода, без дополнительных комментариев. Просто грамотно давайте имена переменным и методам, таким способом вы уменьшите количество необязательных комментариев в вашем коде. Роберт Мартин на этот счет дает совет:

Не тратьте время на написание комментариев, объясняющих созданную вами путаницу, — лучше потратьте его на исправление.

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

$rabbit->runUntilFindVegetables();
$rabbit->runForwardAndTurnBackIfMeet([$wolf, $hunter]);

Но вот это уже перебор:

$rabbit->runForwardUntilFindCarrotOrCabbageAndTurnBackIfMeetWolfOrHunter();

Такой метод тяжело читать, архитектура была выбрана неправильно. Его можно зарефакторить, например, как-то так:

$conditions = new Condition();
 
$untilCondition    = (new Condition\Until())->findVegetables('carrot', 'cabbage');
$turnBackCondition = (new Condition\TurnBack())->ifMeet('wolf', 'hunter');
 
$conditions->add($untilCondition)->add($turnBackCondition);
$rabbit->run(Direction::FORWARD, $conditions);

Есть, правда, и исключения в длине названия методов. Например, когда вы пишете спеки на phpSpec, то можете не ограничивать себя в длине метода, главное, чтоб он передавал всю суть. Вот пример кода, взятого из документации phpSpec:

class MovieSpec extends ObjectBehavior
{
    function it_should_have_john_smith_in_the_cast_with_a_lead_role()
    {
        $this->getCast()->shouldHaveKeyWithValue('leadRole', 'John Smith');
    }
}

В спеках для названий методов используется запись underscore, поэтому глазу легче зацепиться за границы слов и прочитать длинное предложение. Это не по стандарту PSR, где используется camelCase, но для удобочитаемость тестов такой вариант подойдет.

Чувство меры в названиях методов приходит со временем, с опытом. Можно подсмотреть, как это делают в популярных фреймворках и библиотеках.

Характеристики комментариев

Для комментариев свойственные также следующие характеристики.

Неактуальность

Очень часто, меняя код, забывают поменять комментарий. Это особенно актуально, когда над одним участком кода трудятся несколько программистов. Комментарии есть, но они написаны одним из программистов, остальные не решаются изменить чужие комментарии либо ленятся, либо просто не обращают внимание. В результате, старый неактуальный комментарий только запутает нового человека в команде. Решение проблемы простое. Либо всегда следить за актуальностью комментариев, что потребует значительного внимания и стараний. Либо удалить неактуальный комментарий. Отсутствие комментария лучше, чем устарелый, неактуальный комментарий.

Избыточность

Это когда комментарий написан там, где он не нужен, где все понятно и без комментария. Вот пример кода, отягощенного избыточными комментариями.

// Cut the carrot into 4 pieces
$piecesOfCarrot = $carrot / 4;
// Let the rabbit eat all pieces of carrot one by one
foreach ($piecesOfCarrot as $pieceOfCarrot) {
    $rabbit->eat($pieceOfCarrot); // Rabbit eats the piece of carrot
}

Код останется абсолютно понятным, если комментарии уберем, так как код читабельный.

$piecesOfCarrot = $carrot / 4;
foreach ($piecesOfCarrot as $pieceOfCarrot) {
    $rabbit->eat($pieceOfCarrot);
}

Неполнота

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

public function eat($food)
{
    switch ($food) {
        case 'carrot':
            $this->getCalories(50);
            break;
        case 'cabbage':
            $this->getCalories(100);
            break;
        default:
            // If the rabbit eats unknown food - it dies :(
            break;
    }
}

Что означает комментарий, что «кролик умрет»? В жизни этот процесс понятен. А в программе? Что автор хотел сделать после этого? Освободить память занимаемую кроликом? Кинуть исключение и обработать его в другом месте? В данном коде с кроликом ничего не случится, он просто не получит новых калорий от поедания чего-либо, кроме морковки и капусты. Но для нового человека, который будет дописывать код, замысел автора непонятен. Скорее всего новичок удалит комментарий и сделает по-своему.

Недостоверность

Людям свойственно делать ошибки. Программисты их делают не только в коде, но и в комментариях. Либо из-за невнимательности, либо из-за усталости, либо из-за незнания иностранного языка в комментарий вносится путаница и дезинформация. К сожалению, от этого никто не застрахован. Единственное, что можно посоветовать в таком случае — это ответственно относиться к комментариям. Если вы уже решились что-то написать, то пишите грамотно. Перфекционизм в комментариях не помешает 🙂

Неочевидность

Это когда в конкретном месте кода используются неизвестные или не очевидные термины.

// Uses coefficient of rabbit growing per day, which depends on several factors
$rabbit->growInSize();

Тут указывается, что рост кролика определяется каким-то коэффициентом (сам придумал :)), который зависит от каких-то факторов. В данном месте непонятно, что означает коэффициент роста кролика и как он считается. Чтоб разобраться, как работает эта функция, все равно придется переходить в ее описание и изучать код. Лучше комментарий отсюда убрать, а разместить более детальный комментарий в описании самой функции.

Так что, комментарии вообще не писать?

Писать, но нужно брать за них ответственность. Вот моменты, когда они необходимы.

Информативность

В некоторых местах без комментариев не обойтись. Когда нужно объяснить алгоритм или когда группа программистов была вынуждена временно применить какой-то «костыль» в коде, желательно оставить комментарий об этом. Написать, зачем оно было сделано, что оно затрагивает и когда должно быть исправлено. Но все же старайтесь правильно подбирать названия вашим переменным и методам.

Регулярные выражения всегда меня вводят в ступор и приходится тратить достаточно времени, чтоб их расшифровать. В таком случае информативный комментарий не помешает:

// Find all rabbits in locations which
// end on: shire, field, wood
// starts on: yellow, green
// and are not case sensitive
// e.g. Blackshire, Greenfield, Sherwood, SHERWOOD, wood, Yellowstone
$locationsRegExp = '/\b(yellow|green)\w*|\w*(shire|field|wood)\b/i';
$rabbits = $search->findRabbitsInLocations(locationsRegExp);

Намерения

Одну и ту же задачу на языке программирования можно решить многими способами. Программист имеет собственный стиль программирования и, знакомясь с кодом другого программиста, с другим стилем, ему может быть тяжело прочитать код «по диагонали». Если вы обладаете каким-то особым стилем программирования, либо по опыту знаете, что алгоритмы, которые вы используете, тяжело читаются другими, то оставляйте в коде подсказки непосредственно перед началом сложного участка кода.

Предупреждения

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

Усиление

Когда одна строка кода является настолько важной, что необходимо обратить на нее внимание. Например, однажды со мной случился случай, когда на стейджинге не была задана кодировка для мультибайтных функций, я очень долго искал проблему и когда нашел, то добавил в свой код ручную установку параметра с пояснительным комментарием для чего это нужно:

// Set default encoding for MB functions manually to prevent cases when it is missed in config
mb_internal_encoding('UTF-8');

И еще один совет от Роберта Мартина:

Не документируйте плохой код — перепишите его.

Если вам довелось встретиться с жутко непонятным кодом, вы потратили много времени на его разбор, а после решили добавить от себя пару комментариев для будущих разработчиков, то код от этого лучше не станет. В этой ситуации, раз вы уже достаточно разобрались с кодом, попробуйте зарефакторить его до более читабельного состояния. Правило бойскаута гласит: «оставьте место (код) чище, чем было до вашего прихода».

Документируем с помощью докблоков

Есть отдельный вид комментариев в PHP, который имеет свой устоявшийся стандарт — это докблоки (DocBlock). Для обработки докблоков существует инструмент phpDocumentor (ранее известен как phpDoc). Он умеет читать докблоки из кода и строить на их основе документацию. DocBlock — это комбинация DocComment и помещенных в него описаний по стандарту PHPDoc. В PHP есть поддержка C-подобных многострочных комментариев (DocComment):

/*
 * It is
 * a C-style comment in PHP
 */

Докблок отличается дополнительной звездочкой /** в начале комментария:

/**
 * It is
 * a PHP docblock
 */

Докблоком может быть и одна строка, главное, чтоб она начиналась с /**.

/** It is also a docblock */

Стандарт PHPDoc для документирования PHP-кода был реализован на основе уже существующего javaDoc для языка Java. Важной составляющей докблоков являются теги и аннотации, которые предают комментариям семантическую окраску. Тег или аннотация начинается с символа @, например:

/**
 * Login via email and password
 *
 * @param Request $request Request
 *
 * @return Response
 *
 * @throws BadRequestHttpException
 * @throws UnauthorizedHttpException
 *
 * @Rest\Post("/login")
 */
public function loginAction(Request $request)
{
}

В данном примере @param, @return, @throws являются тегами PHPDoc и будут распрарсены с помощью phpDocrumentor’а. @Rest\Post("/login") — это аннотация FOSRestBundle. Отличие аннотаций от тегов в том, что теги просто документируют код, а аннотации меняют или добавляют поведение для кода. Отличительная черта аннотаций PHP от аннотаций Java, в том, что в Java аннотации являются частью языка, а в PHP — всего лишь комментариями, и чтоб к ним достучаться приходиться использовать рефлексию. Возможно в будущем аннотации также станут частью PHP, а пока для их считывания используется вот этот парсер https://github.com/phpDocumentor/ReflectionDocBlock. Так же стоит заметить, что если мы изменим начало докблока с /** на /* это уже не будет считаться докблоком, даже если там есть теги или аннотации, соответственно парсер проигнорирует это место.

Докблоки настолько прижились в коммюнити PHP-программистов, что на их основе готовится PSR-5 (PHP Standard Recommendation). На момент написания статьи он еще находился в черновом варианте.

В PHP с помощью докблоков можно документировать такие элементы:

• функции;
• константы;
• классы;
• интерфейсы;
• трейты;
• константы классов;
• свойства;
• методы.

Важно также, что один докблок может быть применён только к одному структурному элементу. Т.е. на каждую функцию — свой докблок, на переменную внутри функции — свой, для класса — свой.

/**
 * Rabbit Class
 *
 * @version 0.1.0
 */
class Rabbit implements RabbitInterface
{
    const STATUS_RUNNING = 'running';
 
    /**
     * @var string $status Status
     */
    private $status;
 
    /**
     * Set `running` status for the rabbit
     *
     * @return $this
     */
    public function run()
    {
        $this->status = self::STATUS_RUNNING;
 
        return $this;
    }
}

В PHPDoc существует много тегов, но не каждый тег применим ко всем структурным элементам. Ниже предоставлен список существующих тегов, область их использования и объяснение.

• @api (метод) — обозначает стабильные публичные методы, которые не будут менять свою семантику до следующего мажорного релиза.
• @author (в любом месте) — указывает имя и имейл автора, который написал следующий код.
• @copyright (в любом месте) — используется, чтоб поставить свой копирайт в коде.
• @deprecated (в любом месте) — полезный тег, символизирует, что данный элемент исчезнет в будущих версиях. Обычно рядом пишут, какой код следует использовать взамен. Также большинство IDE подсвечивают использование устаревших методов отдельным стилем. Когда нужно подчистить устаревший код для нового релиза, то легко искать по этому тегу.
• @example (в любом месте) — используется для размещения ссылки на файл или веб-страницу, где показан пример использования кода. На данный момент phpDocumentor заявляет о неполной поддержки возможностей этого тега.
• @filesource (файл) — этот тег можно размещать только на самом начале php-файла, так как тег применим только к файлу и включит весь код файла в сгенерированную документацию.
• @global (переменная) — на данный момент этот тег не поддерживается, возможно, будет реализован в следующих версиях, когда он будет переосмыслен.
• @ignore (в любом месте) — докблок, где указан этот тег, не будет обрабатываться во время генерации документации, даже если в нем есть другие теги.
• @internal (в любом месте) — чаще всего используется вместе с тегом @api, чтоб показать, что код предназначен для внутренней логики этой части программы. Элемент, обозначенный этим тегом, не будет включен в документацию.
• @license (файл, класс) — что же он еще может делать, если не указывать тип лицензии для написанного кода.
• @link (в любом месте) — используется для вставки ссылок, но, как пишет документация, полностью функциональность тега пока не поддерживается.
• @method (класс) — применяется к классу и служит для описания магических методов, которые обрабатываются магической функцией __call().
• @package (файл, класс) — разбиение кода на логические подгруппы. Когда вы помещаете классы в один namespace, вы тем самым показывает их функциональную схожесть. Если классы лежат в разных неймспейсах, но имеют одинаковый логический признак, их можно сгруппировать с помощью этого тега, например, если у вас классы работающие с корзиной заказа разбросаны по разным местам. Но лучше отказаться от такой практики, по код стайлу Symfony, например, этот тег не должен использоваться.
• @param (метод, функция) — предназначен для описания входящих параметров функции. Важно также отметить, что если вы уже взялись описывать входящие параметры для конкретной функции через докблоки, то нужно описывать все, а не только первый или второй.
• @property (класс) — так же, как и @method, этот тег размещается в докблоке для класса, но описывает свойства, доступ к которым будет обрабатываться через магические методы __get() и __set().
• @property-read, @property-write (класс) — аналогично предыдущему тегу, но обрабатывают только один магический метод, __get() или __set() соответственно.
• @return (метод, функция) — предназначен для описания значения, которое возвращает функция. Можно указать его тип, и PhpStorm подхватит его и будет выдавать подсказки, но об этом чуть позже.
• @see (в любом месте) — с помощь этого тега можно вставлять ссылки на внешние ресурсы, как и с помощью @link, но также вставлять относительные ссылки на классы и методы.
• @since (в любом месте) — можно указать версию, в которой появился кусок кода.
• @source (в любом месте, кроме начала файла) — с помощью этого тега можно помещать в документацию участки исходного кода (задается строка начала и конца).
• @throws (метод, функция) — используется для указания исключений, которые могут быть вызваны в данной функции.
• @todo (в любом месте) — самый оптимистически тег, используется программистами, чтоб напомнить себе доделать что-то, когда-то в каком-то участке кода. IDE умеют распознавать этот тег и группируют все участки кода в отдельном окне, удобно для будущего поиска. Это общепринятый стандарт и используется очень часто.
• @uses (в любом месте) — предназначен для отображения связи между разными участками кода. Он чем-то похож на @see, но разница в том, что @see создает однонаправленную ссылку, т.е. после перехода на новую страницу документации у вас не будет ссылки назад, а @uses в процессе его обработки ставит обратную ссылку, т.е. ссылку для обратной навигации.
• @var (переменная) — используется для указания типа и описания переменных, как тех, что встречаются внутри функций, так и свойств класса. Следует учесть разницу между этим тегом и тегом @param. Тег @param используется только в докблоках для функций и описывает входящие параметры, а @var используется для документирования обычных переменных.
• @version (в любом месте) — обозначает текущую версию программы, в которой появился данный класс, метод и т.д.

Устаревшие теги, которые, скорее всего, в будущем не будут поддерживаться:

• @category (файл, класс) — использовался для группирования пакетов вместе.
• @subpackage (файл, класс) — использовался для выделения определенных групп в пакетах.

Не все теги одинаково популярны, чаще всего используются: @var, @param, @return, @todo, @throws, остальные — реже. А такие, как @property и @method я вообще еще не встречал в применении, потому что «работать с магией» в PHP — опасно 🙂

Удобство использования докблоков в IDE

Если вы разрабатываете open source проект, то конечно документирование публичного API с помощью докблоков необходимо. Это не только позволит вам сгенерировать готовую документацию, но также позволит использовать ваш код удобно другим разработчикам в своих IDE. Что касается вашего приватного кода для аутсорс проекта, то использование докблоков может показаться не очень уместным, тем не менее советую их использовать, это значительно ускорит вашу разработку.

Для примера возьмем самую популярную IDE для PHP — PhpStorm. Рассмотрим предыдущий пример поиска кроликов:

$rabbits = $search->findRabbitsInLocations('/Sherwood/');
foreach ($rabbits as $rabbit) {
    $rabbit->doSomething();
}

Что хранят в себе переменные $rabbits и $rabbit? PhpStorm об этом ничего не знает. PHP — язык слабо типизированный, тип результата функции не задается жестко из ее описания (привет PHP7, где это будет реализовано). Поэтому вашей IDE нужно подсказать с помощью докблоков, как вести себя с тем или иным кодом. Вариантов есть несколько. Можно сделать так:

/** @var Rabbit $rabbit */
foreach ($rabbits as $rabbit) {
    $rabbit->doSomething();
}

Или добавить тег @return в метод findRabbitsInLocations:

/**
 * @return Rabbit[]
 */
public function findRabbitsInLocations($locations)
{
    // some operations here...
    return [];
}

Обратите внимание, что мы указали Rabbit[], а не Rabbit. Квадратные скобки дают понять, что возвращается массив объектов класса Rabbit, если квадратные скобки убрать, то это будет означать, что метод возвращает один экземпляр класса Rabbit. Еще можно написать так @return null|Rabbit[], вертикальная палка означает «ИЛИ», в данном случае мы указываем, что метод вернет либо массив кроликов, либо null.

Независимо от того, какой способ указания типа вы выбрали, PhpStorm теперь будет выдавать вам подсказки, когда вы напечатаете $rabbit-> и подождете мгновение:

Так происходит потому, что PhpStorm знает, что в переменную $rabbits возвращается массив объектов класса Rabbit. Далее в цикле foreach переменная $rabbit получает один элемент массива, который является экземпляром класса Rabbit и PhpStorm показывает вам доступные публичные методы из этого класса.

Таким образом, не отрываясь от клавиатуры, вы можете использовать классы с публичными методами, которые написали ваши коллеги. PhpStorm будет выдавать вам подсказки, и если метод назван понятно, вы сможете использовать его даже без чтения его исходного кода и документации.

Еще одна полезная фича докблоков в паре с PhpStorm — это предупреждения о неправильных входных параметрах. Допишем докблок для одного из методов класса Rabbit:

/**
 * Run in metres
 *
 * @param int $metres Metres
 */
public function runInMetres($metres)
{
    // some operations here...
}

Тут мы указываем, что на вход должно приходить целое число (опять же, в PHP7 это возможно будет задать на уровне синтаксиса самого языка). Что будет, если мы передадим в этот метод массив?

PhpStorm выделит цветом и выдаст вам подсказку, что на вход ожидается int, а вы передает array. Удобно, правда? Так же подсказки будут выдаваться и на несоответствие классов, интерфейсов. Если ваш метод поддерживает несколько типов для входящих аргументов, то разделите их также через |. В данном примере, если метод runInMetres() также умеет обрабатывать массивы, то в докблок можно дописать «@param int|array $metres Metres» и PhpStorm перестанет ругаться.

PhpStorm также умеет сам генерировать докблоки. Поставте курсор строкой выше на объявление функции, класса или переменной, наберите /** и нажмите Enter, IDE сгенерит вам докблок по шаблону, по желанию можно подправить. Также генерацию докблоков можно запустить через Alt + Insert.

Как соблюдать стили комментирования

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

Чтоб минимизировать дискомфорт, нужно заставить каждого участника команды включить в PhpStorm инспекцию докблоков и отметить там все галочки:

Так же следует использовать PHP CodeSniffer (phpcs) с подходящим вам код стайлом. Не уверен, как насчет всех код стайлов, но для Symfony докблоки являются обязательными. Поэтому phpcs в Шторме будет выдавать вам предупреждения на лету. Настройки делаются в том же месте, а вот еще есть дополнительная инструкция.

Конечно это не заставит всех на 100% придерживаться правил. Но особенных ленивцев можно нагрузить еще одной цитатой из книги «Чистый код», правда, это больше относиться к форматированию кода, но смысл тот же:

«Правила должны соблюдаться всеми участниками группы. Это означает, что каждый участник группы должен быть достаточно разумным, чтобы понимать: неважно, как именно размещаются фигурные скобки, если только все согласились размещать их одинаковым образом.»

Генерация документации с помощью phpDocumentor

Теперь, когда все придерживаются правил, и ваш код покрыт докблоками, можно сгенерировать документацию. Приводить всю документацию по phpDocumentor не буду, всего лишь минимум команд, остальное на официальном сайте.

Итак, нужно установить phpDocumentor. Его можно поставить глобально вот так:

$ wget http://www.phpdoc.org/phpDocumentor.phar
$ chmod +x phpDocumentor.phar
$ sudo mv phpDocumentor.phar /usr/local/bin/phpdoc
$ phpdoc --version

Либо добавить как зависимость в composer.json вашего проекта.

$ composer require --dev "phpdocumentor/phpdocumentor:2.*"

А теперь, находясь в директории проекта, который вы покрыли докблоками, просто запустите из консоли:

$ phpdoc -d src/

Как я и упоминал, это самый минимальный набор действий для генерации документации, опция -d src/ указывает на путь к файлам, которые вы хотите обработать. Сгенерированная документация будет создана в папке output. Конечно же, у этой утилиты есть разные параметры и она умеет разные штуки. А выглядеть сгенерированная документация будет так, можно выбрать существующий шаблон или создать свой.

Генерация документации с помощью Sami

Еще один инструмент для генерации php-документации на основе докблоков — утилита Sami. Возможно, она не такая известная, но я решил ее упомянуть, так как с помощью Sami генерируется документация нашей любимой Symfony.

Консольные команды — Документация Webasyst

Фреймворк Webasyst позволяет выполнять некоторые служебные команды посредством интерфейса командной строки сервера (CLI). Служебные команды предназначены для разработчиков собственных программных продуктов: приложений и плагинов.

Для выполнения служебных команд необходим соответствующий доступ к веб-серверу, на котором установлен фреймворк, например, консоль (терминал) командной строки или SSH. При выполнении команды выполняется вызов интерпретатора PHP с указанием имени файла wa.php, расположенного в корневой директории фреймворка.

• 
  createApp

  Создание приложения.

• 
  createPlugin

  Создание плагина для приложения.

• 
  createSystemplugin

  Создание системного плагина.

• 
  createTheme

  Создание темы дизайна.

• 
  createWidget

  Создание виджета.

• 
  generateDb

  Формирование файла описания таблиц базы данных.

• 
  compress

  Проверка кода и сжатие исходных файлов в архив для публикации в магазине Webasyst.

php wa.php

createApp app_id parameters

Создает базовый набор директорий и файлов, необходимых для разработки нового приложения в директории wa-apps/[app_id]/.

Параметры

• 
  app_id

  Идентификатор приложения (строка в нижнем регистре, например, myapp).

• 
  parameters

  Параметры:

  • -name: Название приложения; если название состоит из нескольких слов, то его нужно заключить в кавычки, например, ‘My app’.
  • -version: Версия приложения, например, 1.0.0.
  • -vendor: Числовой идентификатор разработчика.
  • -frontend: Имеет ли приложение фронтенд (публично доступные страницы).
  • -themes: Поддерживает ли приложение подключение тем дизайна (доступно только при включенном параметре -frontend:).
  • -plugins: Поддерживает ли приложение подключение плагинов.
  • -cli: Имеются ли в приложении обработчики вызовов через командную строку — для выполнения заданий планировщика (cron).
  • -api: Предоставляет ли приложение методы API.

Пример

php wa.php createApp myapp -name 'My app' -version 1.0.0 -vendor 123456 -frontend -themes -plugins -cli -api

php wa.php

createPlugin app_id plugin_id parameters

Создает базовый набор директорий и файлов, необходимых для разработки нового плагина к существующему приложению в директории wa-apps/[app_id]/plugins/[plugin_id].

Параметры

• 
  app_id

  Идентификатор приложения (строка в нижнем регистре, например, myapp).

• 
  plugin_id

  Идентификатор плагина (строка в нижнем регистре, например, myplugin).

• 
  parameters

  Параметры:

  • -name: Название плагина; если название состоит из нескольких слов, то его нужно заключить в кавычки, например, ‘My plugin’.
  • -version: Версия плагина, например, 1.0.0.
  • -vendor: Числовой идентификатор разработчика.
  • -frontend: Имеет ли плагин функции для фронтенда (публично доступных страниц).
  • -settings: Реализован ли в плагине собственный интерфейс настроек (в качестве замены стандартному).

Пример

php wa.php createPlugin someapp myplugin -name 'My plugin' -version 1.0.0 -vendor 123456 -frontend -settings

php wa.php

createSystemplugin type plugin_id parameters

Создает базовый набор директорий и файлов, необходимых для разработки нового системного плагина оплаты, доставки или отправки SMS в директории wa-plugins/[type]/[plugin_id].

Параметры

• 
  type

  Тип плагина: payment, shipping или sms.

• 
  plugin_id

  Идентификатор плагина (строка в нижнем регистре, например, myplugin).

• 
  parameters

  Параметры:

  • -name: Название плагина; если название состоит из нескольких слов, то его нужно заключить в кавычки, например, ‘My shipping’.
  • -version: Версия плагина, например, 1.0.0.
  • -vendor: Числовой идентификатор разработчика.
  • -settings: Предоставляет ли плагин интерфейс для сохранения пользовательских настроек.
  • -prototype: Идентификатор установленного системного плагина того же типа, исходный код которого нужно использовать в качестве образца для создания нового плагина.

Пример

php wa.php createSystemplugin shipping myplugin -name 'My shipping' -version 1.0.0 -vendor 123456 -prototype courier

php wa.php

createTheme app_id[,app_id_2[,…]] theme_id parameters

Создает базовый набор директорий и файлов, необходимых для разработки новой темы дизайна.

Параметры

• 
  app_id[,app_id_2[,…]]

  Идентификатор одного приложения или идентификаторы нескольких приложений через запятую. Вместо перечисления всех приложений с поддержкой фронтенда, доступных в бекенде разработчика, можно указать символ * (звёздочка).

• 
  theme_id

  Идентификатор темы дизайна (строка в нижнем регистре, например, mytheme).

• 
  parameters

  Параметры:

  • -name: Название темы дизайна; если название состоит из нескольких слов, то его нужно заключить в кавычки, например, ‘My widget’.
  • -parent: Идентификатор родительской темы дизайна.
  • -version: Версия темы дизайна, например, 1.0.0.
  • -vendor: Числовой идентификатор разработчика.
  • -prototype: Идентификатор установленной темы, которая будет использована в качестве прототипа. По умолчанию в качестве прототипа используется тема дизайна с идентификатором default.

Пример

php wa.php createTheme site,shop,blog mytheme -name 'My theme' -version 1.0.0 -vendor 123456 -prototype dummy

php wa.php

createWidget app_id widget_id parameters

Создает базовый набор директорий и файлов, необходимых для разработки нового виджета.

Параметры

• 
  app_id

  Идентификатор приложения. Если необходимо создать общесистемный плагин в директории wa-widgets/, следует указать идентификатор приложения webasyst.

• 
  widget_id

  Идентификатор виджета (строка в нижнем регистре, например, mywidget).

• 
  parameters

  Параметры:

  • -name: Название виджета; если название состоит из нескольких слов, то его нужно заключить в кавычки, например, ‘My widget’.
  • -version: Версия виджета, например, 1.0.0.
  • -vendor: Числовой идентификатор разработчика.
  • -settings: Предоставляет ли виджет интерфейс для сохранения пользовательских настроек.

Пример

php wa.php createWidget shop mywidget -name 'My widget' -version 1.0.0 -vendor 123456 -settings

php wa.php

generateDb app_id/plugin_id tables -update

Формирует либо обновляет конфигурационный файл описания базы данных приложения или плагина lib/config/db.php.

Параметры

• 
  app_id

  Идентификатор приложения (строка в нижнем регистре, например, myapp).

• 
  plugin_id

  Необязательный идентификатор плагина — если необходимо сформировать файл db.php для плагина, а не приложения.

• 
  tables

  Список названий таблиц, разделенных пробелами, описания которых необходимо добавить в файл.

• 
  -update

  Необязательный параметр, позволяющий обновить содержимое уже существующего файла.

Примеры для приложения

#создание файла db.php
php wa.php generateDb myapp myapp_items myapp_types

#обновление файла db.php
php wa.php generateDb myapp myapp_items myapp_types -update

Примеры для плагина

#создание файла db.php
php wa.php generateDb someapp/myplugin myplugin_items myplugin_types

#обновление файла db.php
php wa.php generateDb someapp/myplugin myplugin_items myplugin_types -update

php wa.php

compress slug params

Выполняет базовую проверку программного кода и сжатие исходных файлов в архив для публикации в магазине Webasyst.

Параметры

Примеры

# проверить код без подключенных продуктов третьих сторон и сжать файлы в архив
php wa.php compress someapp/plugins/myplugin

# проверить код вместе c подключенными продуктами третьих сторон и сжать файлы в архив
php wa.php compress someapp/plugins/myplugin -style true

# проверить код без подключенных продуктов третьих сторон, не сжимая файлы в архив
php wa.php compress someapp/plugins/myplugin -skip compress

# сжать файлы в архив без какой-либо проверки
php wa.php compress someapp/plugins/myplugin -skip test

PHP | Русскоязычная документация по Ubuntu

Начиная с версии Ubuntu 16.04 (Xenial Xerus) используется PHP версии 7. Информация о PHP версии 5 (в более ранних версиях Ubuntu) находится на странице PHP5.

PHP – скриптовый язык программирования общего назначения, интенсивно применяемый для разработки веб-приложений.

Версии PHP в Ubuntu

Варианты использования PHP

Интерпретатор PHP поставляется в нескольких вариантах для разных способов запуска и использования PHP:

Модуль для Apache

Установка

Для установки выполните:

sudo apt-get install libapache2-mod-php

Настройка

Файлы настройки PHP модуля для Apache располагаются в директории /etc/php/7.0/apache2. Данная директория содержит:

• conf.d — директория с настройками активных PHP-расширений;
• php.ini — файл настройки PHP.

После изменения файлов настройки PHP или изменения PHP-расширений требуется перезапуск сервера Apache:

sudo service apache2 reload

Проверка работы

В директории /var/www/html (или в корне любого другого виртуального хоста) создайте файл test.php и запишите в него следующую строку:

<?php phpinfo();

Теперь попробуйте в своем браузере перейти на созданную страницу http://localhost/test.php. Если вы видите описание установленного PHP, значит вы все настроили правильно.

php-fpm

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

Установка

Для установки выполните:

Если установлен libmod-php то его надо сначала выключить sudo a2dismod a2dismod php7.2.conf

sudo apt-get install php-fpm
sudo a2enmod proxy_fcgi
sudo a2enconf php7.2-fpm.conf

Настройка

Файлы настройки PHP в виде модуля для Apache располагаются в директории /etc/php/7.0/fpm. Данная директория содержит:

После изменения файлов настройки PHP или изменения PHP-расширений требуется перезапуск FPM:

sudo service php7.0-fpm reload
sudo systemctl restart apache2

CLI

CLI (интерпретатор командной строки) предоставляет возможность разрабатывать консольные приложения на PHP.

Установка

Для установки выполните:

sudo apt-get install php-cli

Настройка

Файлы настройки CLI располагаются в директории /etc/php/7.0/cli. Данная директория содержит:

• conf.d — директория с настройками активных PHP-расширений;
• php.ini — файл настройки PHP.

PHP расширения

Дополнительный функционал в PHP реализован с помощью расширений. Некоторые расширения могут сразу поставляться с интерпретатором, а некоторые расширения следует устанавливать дополнительно.

Установка

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

Подключение расширения GD:

sudo apt-get install php-gd

Подключение расширения MySQL:

sudo apt-get install php-mysql

Подключение расширения Mcrypt:

sudo apt-get install php-mcrypt

Настройка

Файлы настроек доступных расширений располагаются в директории /etc/php/7.0/mods-available. У каждого варианта запуска интерпретатора существует своя директория conf.d в которой находятся символьные ссылки на активные расширения.

Установка других версий PHP

Данный способ показывает, как установить версию PHP, не входящую в стандартные репозитории вашей версии Ubuntu. Для установки используются пакеты из PPA.

1. Посмотрите список установленных пакетов PHP для удаления ненужных:

dpkg -l | grep php| awk '{print $2}' |tr "\n" " "

2. Добавьте PPA в список репозиториев:

sudo add-apt-repository ppa:ondrej/php
sudo apt-get update

3. Установите вашу версию PHP.

Пример установки PHP версии 5.6:

sudo apt-get install php5.6

Пример установки некоторых модулей для PHP версии 5.6:

sudo apt-get install php5.6-mbstring php5.6-mcrypt php5.6-mysql php5.6-xml

Ссылки

Документация/PHP

Программное обеспечение, документация, драйвера, утилиты к интегрированной системе видеорегистрации и аудиозаписи TRASSIR

Документация — 3.10

Внести вклад в документацию просто. Файлы размещаются на
https://github.com/cakephp/docs. Не стесняйтесь произвести форк репозитория, добавить своё
изменение/улучшение/перевод и возвратить, выдав запрос на pull request (перенос).
Вы даже можете редактировать документы в Интернете с помощью GitHub, не загружая
файлы – кнопка «Improve this Doc» на любой странице приведёт вас к редактору GitHub для этой страницы.

Документация CakePHP
непрерывно интегрируемая,
и развёртывается после каждого запроса pull request, на слияние.

Переводы

Отправьте по электронной почте команду docs (docs на cakephp dot org) или перейдите на IRC
(#cakephp on freenode), чтобы обсудить любые усилия по переводу если хотите участвовать.

Новый язык перевода

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

Если ваш язык не находится в списке текущих языков, свяжитесь с нами через
Github, и мы рассмотрим создание для него папки скелета. Следующие
разделы являются первыми, которые вы должны рассмотреть,
файлы не меняются часто:

Напоминание для администраторов документов

Структура всех языковых папок должна отражать состав английской папки.
Если структура изменена для английской версии, вы должны применить
эти изменения и для других языков.

Например, если в en/file.rst создан новый английский файл, вы должны:

• Добавить файл и для других языков. : fr/file.rst, zh/file.rst, …

• Удалить содержимое, но сохраняя информацию title, meta и возможные toc-tree элементы.
  Следующее примечание будет добавлено, пока никто не перевёл файл:

  File Title
  ##########
  
  .. note::
      The documentation is not currently supported in XX language for this
      page.
  
      Please feel free to send us a pull request on
      `Github <https://github.com/cakephp/docs>`_ or use the **Improve This Doc**
      button to directly propose your changes.
  
      You can refer to the English version in the select top menu to have
      information about this page's topic.
  
  // Если элементы toc-tree находятся в английской версии
  .. toctree::
      :maxdepth: 1
  
      one-toc-file
      other-toc-file
  
  .. meta::
      :title lang=xx: File Title
      :keywords lang=xx: title, description,...
  

Советы переводчикам

• Выберите ваш язык, на который вы хотите перевести контент, и просмотрите что уже переведено.

• Не стесняйтесь использовать ваш язык, если он уже существует в книге.

• Используйте Неофициальные формы.

• Переведите одновременно и контент и заголовок.

• По сравнению с английским содержанием, перед отправкой исправления,
  (если вы что-то исправите, но не интегрируете изменение «вверх по течению» („upstream“)
  ваше изменение не будет принято).

• Если вам нужно написать английский термин, оберните его в теги <em>.
  Например. «asdf asdf Controller asdf» или «asdf asdf Kontroller (Controller) asfd».

• Не отправляйте частичные(незаконченные) переводы.

• Не редактируйте раздел ожидающий изменений.

• Не используйте
  HTML сущности
  для акцентирования. В книге используется кодировка UTF-8.

• Не меняйте разметку (HTML) и не добавляйте новый контент.

• Если в исходном контенте отсутствует какая-либо информация, отправьте
  её в первую очередь.

Руководство по форматированию документации

Новая документация CakePHP написана с помощью
Текста в формате ReST. ReST
(Re Structured Text) — синтаксис простой текстовой разметки, аналогичный markdown (методу уценки), или
textile. Для поддержания согласованности рекомендуется, чтобы при добавлении к
CakePHP вы следовали этим рекомендациям, о том как форматировать и
структурировать свой текст.

Длина строки

Строки текста должны быть обернуты в 80 столбцов (80 символов на строке). Единственным исключение могут быть
длинные URL-адреса и фрагменты кода. Используется для под-подразделов.

Заголовки не должны вставляться в глубину более 5 уровней. Перед заголовками и после
должна идти пустая строка.

Параграфы

Параграфы — это просто блоки текста, причем все линии имеют одинаковые
отступы друг от друга. Параграфы должны быть разделены одной пустой строкой.

Встроенная разметка

• Одна звездочка: текст для выделения (курсивом)
  Мы используем его для общего выделения/акцента.

• Две звездочки: текст для выделения жирным (полужирный)
  Мы будем использовать его для имён рабочих каталогов, тем списка, имён таблиц и
  исключая следующее слово «table».

• Две косых черты(засечки): text для образцов кода.
  Мы будем использовать его для имён параметров метода, имён столбцов таблицы, имён объектов,
  за исключением следующего слова «object» и для имён методов/функций
  – include «()».

  • ``cascadeCallbacks``, ``true``, ``id``,
    ``PagesController``, ``config()``, etc.

Если в рабочем тексте появляются звездочки или косые чёрточки(засечки), и они могут сломать
встроенную разметку, они должны быть экранированы обратной косой чертой.

Встроенная разметка имеет несколько ограничений:

• Это не может быть вложением.

• Содержимое не может начинаться или заканчиваться пробелами: * text* это ошибка.

• Содержимое должно быть отделено от окружающего текста non-word символами. Используйте
  обратную косую черту, чтобы избежать удаления пробелов: onelong\ *bolded*\ word.

Списки

Разметка списка очень похожа на пометки. Неупорядоченные списки указываются
начиная строку с одной звездочки и пробела. Нумерованные списки могут быть
созданны с помощью либо цифр, либо # для автоматической нумерации:

* This is a bullet
* So is this. But this line
  has two lines.

1. First line
2. Second line

#. Automatic numbering
#. Will save you some time.

Также можно создавать списки используя отступы, и разделять их
пустой строкой:

* First line
* Second line

    * Going deeper
    * Whoah

* Back to the first level.

Списки определений можно сделать так:

term
    definition
CakePHP
    An MVC framework for PHP

Термины не могут быть больше одной строки, но определения могут быть многострочными и все
линии должны иметь постоянный отступ.

Ссылки

Существует несколько видов ссылок, и каждый вид имеет своё собственное применение.

Внешние ссылки

Ссылки на внешние документы (ресурсы) могут быть выполнены с помощью следующего:

`External Link to php.net <http://php.net>`_

Полученная ссылка будет выглядеть так: External Link to php.net

Ссылки на другие страницы

:doc:

Разные страницы документации могут быть связаны между собой с использованием роли :doc:.
Вы можете ссылаться на указанный документ, используя абсолютный или относительный
путь. Вы должны опустить расширение .rst. Например, если в документе core-helpers/html
используется ссылка :doc:`form`, то это значит, что она ссылается на
core-helpers/form. Если ссылка была такого вида :doc:`/core-helpers`, то она всегда будет ссылаться на /core-helpers, независимо от места её использования.

Перекрестные ссылки

:ref:

Вы можете перекрёстно ссылаться на любой произвольный заголовок в любом документе, используя
:ref: роль. Цели ссылок на метки должны быть уникальными на всём протяжении
документации. При создании меток на методы класса, лучше всего использовать
class-method в качестве формата вашей метки ссылок.

Наиболее распространенно использование меток над заголовком. Пример:

.. _label-name:

Section heading
---------------

More content here.

В другом месте вы можете ссылаться на вышеуказанный раздел, используя :ref:`label-name`.
Текст ссылки будет названием, которому предшествовала ссылка. Вы также можете
ввести текст пользовательской ссылки, используя :ref:`Link text <label-name>`.

Предотвращение предупреждений от Sphinx

Sphinx выводит предупреждения, если файл не ссылается в toc-tree. Это
отличный способ гарантировать, что все файлы имеют ссылку, направленную на них, но
иногда вам не нужно вставлять ссылку на файл, например для ваших
epub-contents и pdf-contents файлов. В этих случаях вы можете добавить
:orphan: в верхней части файла, чтобы подавить предупреждения о том, что файл не
в toc-tree.

Описание классов и их содержания

В документации CakePHP используется phpdomain для предоставления пользовательских
директив для описания объектов и конструкций PHP. Использование этих директив
и ролей необходимо для правильной индексации и перекрёстных ссылок.

Описание классов и конструкторов

Каждая директива описывает индекс и/или пространство имен.

.. php:global:: name

Эта директива объявляет новую глобальную переменную PHP.

.. php:function:: name(signature)

Определяет новую глобальную функцию вне класса.

.. php:const:: name

Эта директива объявляет новую константу PHP. Вы также можете использовать вложенние
внутрь директивы класса, для создания констант класса.

.. php:exception:: name

Эта директива объявляет новое исключение в текущем пространстве имен.
Подпись может включать аргументы конструктора.

.. php:class:: name

Описывает класс. Методы, атрибуты и константы, принадлежащие классу,
должны находиться внутри тела этой директивы:

.. php:class:: MyClass

    Описание класса

   .. php:method:: method($argument)

    Описание метода

Атрибуты, методы и константы не обязательно должны быть вложенными. Они также могут просто
следовать декларации класса:

.. php:class:: MyClass

    Текст о классе

.. php:method:: methodName()

    Текст о методе

.. php:method:: name(signature)

Описать метод класса, его аргументы, возвращаемое значение и исключения:

.. php:method:: instanceMethod($one, $two)

    :param string $one: The first parameter.
    :param string $two: The second parameter.
    :returns: An array of stuff.
    :throws: InvalidArgumentException

   This is an instance method.

.. php:staticmethod:: ClassName::methodName(signature)

Опишите статический метод, его аргументы, возвращаемое значение и исключения,
см. php:method для использования параметров.

.. php:attr:: name

Описать свойство/атрибут для класса.

Предотвращение предупреждений от Sphinx

Sphinx выводит предупреждения, если функция ссылается на несколько файлов. Это
отличный способ гарантировать, что вы не добавляли функцию два раза, но
иногда вы действительно хотите написать функцию в двух или более файлах, например.
/development/debugging ссылается на /development/debugging и на
/core-libraries/global-constants-and-functions. В этом случае вы можете добавить
:noindex: под функцией debug для подавления предупреждений. Сохраните хотя бы
одну ссылку без :no-index: чтобы сохранить ссылку на функцию:

.. php:function:: debug(mixed $var, boolean $showHtml = null, $showFrom = true)
    :noindex:

Перекрестная ссылка

Следующие роли относятся к объектам PHP, а ссылки генерируются, если
найдена соответствующая директива:

:php:func:

Ссылка на функцию PHP.

:php:global:

Ссылка на глобальную переменную, имя которой имеет префикс $.

:php:const:

Укажите глобальную константу или константу класса. Константы класса
должны предшествовать имени класса:

DateTime has an :php:const:`DateTime::ATOM` constant.

:php:class:

Ссылка на класс по имени:

:php:meth:

Ссылка на метод класса. Эта роль поддерживает оба вида методов:

:php:meth:`DateTime::setDate`
:php:meth:`Classname::staticMethod`

:php:attr:

Ссылка на свойство объекта:

:php:attr:`ClassName::$propertyName`

:php:exc:

Ссылка на исключение.

Исходный код

Буквенные кодовые блоки создаются путем окончания абзаца на ::. Литерал
блока должен быть отступом, и, как и все абзацы, должен разделяться одиночными линиями:

Это абзац::

    while ($i--) {
        doStuff()
    }

Это снова очередной текст.

Буквенный текст не изменяется или не форматируется, за исключением того, что удаляется один уровень отступов.

Примечания и предупреждения

Часто так бывает, что вы хотите сообщить читателю важный совет,
специальное примечание или потенциальную опасность. Упоминания в sphinx используются только для
этого. Есть пять видов предупреждений.

• .. tip:: Советы используются для документирования или повторного использования интересной или важной информации. Содержание директивы должно быть написано полностью в одном предложении и включать все соответствующие знаки препинания.

• .. note:: Примечания используются для документирования особо важной части информации. Содержание директивы должно быть написано полностью в одном предложении и включать все соответствующие знаки препинания.

• .. warning:: Предупреждения используются для документирования потенциальных камней преткновения или информации, относящейся к безопасности. Содержание директивы должно быть написано в полных предложениях и включать все соответствующие знаки препинания.

• .. versionadded:: X.Y.Z «Version added» заметки используются для отображения предупреждений специально для новых функций, добавленных в определенной версии, X.Y.Z является версией с который была добавлена эта функция.

• .. deprecated:: X.Y.Z В отличие от предупреждений «version added», «deprecated» предупреждения используются для уведомления об устаревшей функции, X.Y.Z является версией на которой упомянутый признак устарел.

Все примечания сделаны одинаковыми:

.. note::

    Отступ и предшествует и следует пустая строка. Так же, как для параграфа.

Этот текст не является частью примечания.

Образец

Совет

Это полезный tid-bit, который вы вероятно забыли.

Примечание

Вы должны обратить внимание на это.

Предупреждение

Это может быть опасно.

Добавлено в версии 2.6.3: Эта замечательная функция была добавлена в версию 2.6.3

Не рекомендуется, начиная с версии 2.6.3: Эта старая функция стала устаревшей в версии 2.6.3

Установка (Laravel 8.x) — Laravel Framework Russian Community

Это скорректированный автоматический перевод, сделанный при помощи google translate.

Перевод немного отстаёт от оригинала

Встречайте Laravel

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

Laravel стремится обеспечить потрясающий опыт разработчика, предоставляя при этом мощный функционал: тщательное внедрение зависимостей, выразительный уровень абстракции базы данных, очереди и запланированные задачи, модульное и интеграционное тестирование и многое другое.

Независимо от того, новичок ли вы в PHP, веб-фреймворках или имеете многолетний опыт, Laravel – это фреймворк, который может расти вместе с вами. Мы поможем вам сделать первые шаги в качестве веб-разработчика или подскажем, как вы поднимите свой опыт на новый уровень. Нам не терпится увидеть, что вы построите.

Почему именно Laravel?

При создании веб-приложения вам доступны различные инструменты и фреймворки. Однако мы считаем, что Laravel – лучший выбор для создания современных полнофункциональных веб-приложений.

Прогрессивный фреймворк

Нам нравится называть Laravel «прогрессивным» фреймворком. Под этим мы подразумеваем, что Laravel растет вместе с вами. Если вы только делаете первые шаги в веб-разработке, обширная библиотека документации, руководств и видеоуроков Laravel поможет вам изучить основы, не перегружая себя.

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

Масштабируемый фреймворк

Laravel невероятно масштабируем. Благодаря удобному для масштабирования характеру PHP и встроенной поддержке быстрых распределенных систем кеширования, таких как Redis, горизонтальное масштабирование с Laravel очень просто. Фактически, приложения Laravel легко масштабируются для обработки сотен миллионов запросов в месяц.

Требуется экстремальное масштабирование? Такие платформы, как Laravel Vapor, позволяют запускать приложение Laravel в практически неограниченном масштабе с использованием новейшей бессерверной технологии AWS.

Фреймворк сообщества

Laravel объединяет лучшие пакеты в экосистеме PHP, чтобы предложить наиболее надежный и удобный для разработчиков фреймворк. Кроме того, тысячи талантливых разработчиков со всего мира внесли свой вклад в фреймворк. Кто знает, возможно, вы даже станете соучастником Laravel.

Ваш первый проект на Laravel

Мы хотим, чтобы начать работу с Laravel было как можно проще. Существует множество вариантов разработки и запуска проекта Laravel на вашем собственном компьютере. Хотя вы, возможно, захотите изучить эти варианты позже, но Laravel предлагает Sail – встроенное решение для запуска вашего проекта Laravel с помощью Docker.

Docker – это инструмент для запуска приложений и служб в небольших, легких «контейнерах», которые не мешают установленному на вашем локальном компьютере программному обеспечению или его конфигурации. Это означает, что вам не нужно беспокоиться о конфигурировании или настройке сложных инструментов разработки, таких как веб-серверы и базы данных на вашем персональном компьютере. Для начала вам нужно всего лишь установить Docker Desktop.

Laravel Sail – это легкий интерфейс командной строки для взаимодействия с конфигурацией Docker по умолчанию в Laravel. Sail обеспечивает отличную отправную точку для создания приложения Laravel с использованием PHP, MySQL и Redis без предварительного опыта работы с Docker.

Уже знаком с Docker? Не волнуйтесь! Все в Sail можно перенастроить с помощью файла docker-compose.yml, входящего в Laravel.

Начало работы в macOS

Если вы разрабатываете на Mac и Docker Desktop уже установлен, то вы можете использовать простую команду терминала для создания нового проекта Laravel. Например, чтобы создать новое приложение Laravel в каталоге с именем example-app, вы можете запустить следующую команду в своем терминале:

curl -s https://laravel.build/example-app | bash

Конечно, вы можете изменить example-app в этом URL на что угодно. Каталог приложения Laravel будет создан в каталоге, из которого вы выполняете команду.

После создания проекта вы можете перейти в каталог приложения и запустить Laravel Sail. Laravel Sail предлагает простой интерфейс командной строки для взаимодействия с конфигурацией Docker по умолчанию в Laravel:

cd example-app

./vendor/bin/sail up

При первом запуске команды up Sail на вашем компьютере будут созданы контейнеры приложений Sail. Это может занять несколько минут. Не волнуйтесь, последующие попытки запустить Sail будут намного быстрее.

После запуска контейнеров приложения Docker, вы можете получить доступ к приложению в своем веб-браузере по адресу: http://localhost.

Чтобы продолжить изучение Laravel Sail, просмотрите его полную документацию.

Начало работы в Windows

Прежде чем мы создадим новое приложение Laravel на вашем компьютере с Windows, обязательно установите Docker Desktop. Затем вы должны убедиться, что подсистема Windows для Linux 2 (WSL2) установлена и включена. WSL позволяет запускать двоичные исполняемые файлы Linux прямо в Windows 10. Информацию о том, как установить и включить WSL2, можно найти в документации Среда разработки.

После установки и включения WSL2 вы должны убедиться, что Docker Desktop настроен на использование серверной части WSL2.

Теперь вы готовы создать свой первый проект Laravel. Запустите Терминал Windows и начните новый сеанс терминала для вашей операционной системы WSL2 Linux. Затем вы можете использовать простую команду терминала для создания нового проекта Laravel. Например, чтобы создать новое приложение Laravel в каталоге с именем example-app, вы можете запустить следующую команду в своем терминале:

curl -s https://laravel.build/example-app | bash

Конечно, вы можете изменить example-app в этом URL на что угодно. Каталог приложения Laravel будет создан в каталоге, из которого вы выполняете команду.

После создания проекта вы можете перейти в каталог приложения и запустить Laravel Sail. Laravel Sail предлагает простой интерфейс командной строки для взаимодействия с конфигурацией Docker по умолчанию в Laravel:

cd example-app

./vendor/bin/sail up

При первом запуске команды up Sail на вашем компьютере будут созданы контейнеры приложений Sail. Это может занять несколько минут. Не волнуйтесь, последующие попытки запустить Sail будут намного быстрее.

После запуска контейнеров приложения Docker, вы можете получить доступ к приложению в своем веб-браузере по адресу: http://localhost.

Чтобы продолжить изучение Laravel Sail, просмотрите его полную документацию.

Разработка в подсистеме WSL2

Конечно, вам нужно будет иметь возможность изменять файлы приложения Laravel, которые были созданы в вашей установке WSL2. Для этого мы рекомендуем использовать редактор Microsoft Visual Studio Code и его собственное расширение Remote Development.

После установки этих инструментов вы можете открыть любой проект Laravel, выполнив из корневого каталога вашего приложения команду code . с помощью Терминала Windows.

Начало работы в Linux

Если вы разрабатываете в Linux и Docker Desktop уже установлен, то вы можете использовать простую команду терминала для создания нового проекта Laravel. Например, чтобы создать новое приложение Laravel в каталоге с именем example-app, вы можете запустить следующую команду в своем терминале:

curl -s https://laravel.build/example-app | bash

Конечно, вы можете изменить example-app в этом URL на что угодно. Каталог приложения Laravel будет создан в каталоге, из которого вы выполняете команду.

После создания проекта вы можете перейти в каталог приложения и запустить Laravel Sail. Laravel Sail предлагает простой интерфейс командной строки для взаимодействия с конфигурацией Docker по умолчанию в Laravel:

cd example-app

./vendor/bin/sail up

При первом запуске команды up Sail на вашем компьютере будут созданы контейнеры приложений Sail. Это может занять несколько минут. Не волнуйтесь, последующие попытки запустить Sail будут намного быстрее.

После запуска контейнеров приложения Docker, вы можете получить доступ к приложению в своем веб-браузере по адресу: http://localhost.

Чтобы продолжить изучение Laravel Sail, просмотрите его полную документацию.

Выбор служб Sail

При создании нового приложения Laravel через Sail вы можете использовать строковую переменную запроса with, чтобы выбрать, какие службы должны быть настроены в файле docker-compose.yml вашего нового приложения. Доступны следующие службы mysql, pgsql, mariadb, redis, memcached, meilisearch, selenium и mailhog:

curl -s "https://laravel.build/example-app?with=mysql,redis" | bash

Если вы не укажете желаемые службы, то будет сконфигурирован стек по умолчанию из mysql, redis, meilisearch, mailhog и selenium.

Установка через Composer

Если на вашем компьютере уже установлены PHP и Composer, то вы можете создать новый проект Laravel напрямую с помощью Composer. После того, как приложение было создано, вы можете запустить локальный сервер разработки Laravel с помощью команды serve Artisan CLI:

composer create-project laravel/laravel example-app

cd example-app

php artisan serve

Установщик Laravel

В качестве альтернативы, вы можете использовать установщик Laravel, включив его в глобальную зависимость Composer:

composer global require laravel/installer

laravel new example-app

cd example-app

php artisan serve

Чтобы исполняемый файл laravel мог быть обнаружен вашей системой, удостоверьтесь в правильном расположении каталога bin менеджера пакетов Composer, задаваемый системной переменной $PATH. Расположение каталога зависит от вашей операционной системы, но типичными могут быть:

• macOS: $HOME/.composer/vendor/bin
• Windows: %USERPROFILE%\AppData\Roaming\Composer\vendor\bin
• GNU / Linux Distributions: $HOME/.config/composer/vendor/bin или $HOME/.composer/vendor/bin

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

laravel new example-app --git

Эта команда инициализирует новый репозиторий Git для вашего проекта и автоматически зафиксирует базовый каркас Laravel. Флаг --git предполагает, что вы правильно установили и настроили Git. Можно также использовать параметр --branch, чтобы задать имя ответвления:

laravel new example-app --git --branch="main"

Вместо использования флага --git вы можете использовать параметр --github, чтобы создать репозиторий Git и, соответствующий ему, частный репозиторий на GitHub:

laravel new example-app --github

Созданный репозиторий будет доступен по адресу https://github.com/<your-account>/example-app. Параметр --github предполагает, что вы правильно установили GitHub CLI и прошли аутентификацию с помощью интерфейса командной строки. Кроме того, у вас должен быть установлен и правильно настроен git. При необходимости вы можете передать дополнительные параметры и флаги, поддерживаемые GitHub CLI:

laravel new example-app --github="--public"

Можно использовать параметр --organization для создания репозитория под определенной организацией GitHub:

laravel new example-app --github="--public" --organization="laravel"

Начальная конфигурация

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

Laravel практически не требует дополнительной настройки из коробки. Вы можете начать разработку! Однако вы можете просмотреть файл config/app.php и его комментарии. Он содержит несколько параметров, таких как часовой пояс и локаль, которые вы можете изменить в соответствии с вашим приложением.

Конфигурация на основе окружения

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

Ваш файл .env не должен быть привязан к системе контроля версий вашего приложения, поскольку каждому разработчику / серверу, использующему ваше приложение, может потребоваться другая конфигурация окружения. Более того, это будет угрозой безопасности в случае, если злоумышленник получит доступ к вашему репозиторию системы управления версиями, поскольку любые конфиденциальные учетные данные будут раскрыты.

Для получения дополнительной информации о конфигурации на основе файла .env и окружения ознакомьтесь с полной документацией по конфигурации.

Конфигурация каталога

Laravel всегда должен обслуживаться из корня «веб-каталога», настроенного для вашего веб-сервера. Вы не должны пытаться обслуживать приложение Laravel из поддиректории относительно «веб-каталога». Такая попытка может открыть доступ к конфиденциальным файлам, существующим в вашем приложении.

Следующие шаги

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

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

Laravel как клиент-серверный фреймворк

Laravel может служить клиент-серверным фреймворком. Под «клиент-серверным фреймворком» мы подразумеваем, что вы собираетесь использовать Laravel для маршрутизации запросов к вашему приложению и отрисовки интерфейса через шаблоны Blade или с использованием гибридной технологии одностраничного приложения, такой как Inertia.js. Это наиболее распространенный способ использования фреймворка Laravel.

Если вы планируете использовать Laravel именно таким образом, вы можете ознакомиться с нашей документацией по маршрутизации, представлениям или Eloquent ORM. Кроме того, вам может быть интересно узнать о таких пакетах сообщества, как Livewire и Inertia.js. Эти пакеты позволяют использовать Laravel в качестве фреймворка полного стека, при этом пользуясь многими преимуществами UI, предоставляемыми одностраничными JavaScript-приложениями.

Если вы используете Laravel в качестве фреймворка полного стека, мы также настоятельно рекомендуем вам научиться компилировать CSS и JavaScript вашего приложения с помощью Laravel Mix.

Если вы хотите получить преимущество перед созданием своего приложения, ознакомьтесь с одним из наших официальных стартовых комплектов приложений.

Laravel в качестве сервера API

Laravel также может служить серверной частью API для одностраничного JavaScript-приложения или мобильного приложения. Например, вы можете использовать Laravel в качестве серверной части API для своего Next.js приложения. В этом контексте вы можете использовать Laravel для обеспечения аутентификации и хранения / получения данных для вашего приложения, а также пользуясь преимуществами мощных служб Laravel, таких как очереди, электронная почта, уведомления и многое другое.

Если вы планируете использовать Laravel именно так, то вы можете ознакомиться с нашей документацией по маршрутизации, пакету Laravel Sanctum и Eloquent ORM.

Комментирование кода и генерация документации PHP

Зачем нужны комментарии в коде? Как их написать? Где они нужны, а где нет? Как правильно комментировать код? Как создать единый стиль документации для всех членов команды? Какие есть инструменты для создания документации? Я постараюсь ответить на все вопросы и поделиться с вами своими мыслями по этому поводу.

Итак, существует два типа программной документации.Первый тип — написать комментарий в самом коде. Второй вариант — когда используется сторонний инструмент или репозиторий, например WIKI-движок, где описаны принципы работы приложения, примеры использования, модули взаимодействия, а также представлены блок-схемы и диаграммы, в общем все, что вы не можете писать в коде.

Варианты расположения документации

Начнем с документации внутри программного кода. Однако это не является целью данной статьи.В проектах с открытым исходным кодом мы часто можем заметить, что статьи документации хранятся в том же репозитории, что и базовый код. Например, в библиотеке фальшивых фикстур PHP документация находится в файле README, и если вы хотите прочитать ее до конца, вам придется немного прокрутить. В популярном HTTP-клиенте для PHP Guzzle есть инструкции по использованию. хранится в отдельной папке с документами. Хранить документацию близко к коду — это хорошо и очень удобно. Скачав один раз пакет поставщиков, вы получите код и документацию.Если ваша библиотека невелика, если она стабильна и не требует частых изменений API в будущем, что приведет к постоянному переписыванию документации, вы можете безопасно разместить документацию в репозитории вашего проекта.

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

В этом случае лучше создать отдельный репозиторий для документации, например, как это было сделано для Symfony.GitHub, GitLab, Bitbucket также предоставляют встроенный инструмент WIKI, который прикреплен к проекту и не является автономным репозиторием. Но вы также можете получить к нему доступ через Git, что означает, что вы можете копировать всю документацию, редактировать ее в редакторе, который вам больше нравится, группировать изменения в коммиты, отправлять их на сервер и получать новые комментарии.

Вот пример хорошо организованной библиотеки визуализации WIKI для D3.js. Конечно, можно создать веб-сайт для продукта и разместить там его документацию.Но если вы воспользуетесь одним из описанных выше методов, вы сможете создавать веб-страницы документации из репозитория Git или WIKI — для этого есть инструменты. Если вы предпочитаете комплексные решения, вам стоит обратить внимание на Confluence от Atlassian. У него гораздо больше возможностей, чем у WIKI-движка.

Код комментария внутри кода

А теперь вернемся к документированию кода в самом коде. Я пишу эту статью, основываясь на собственном опыте, но недавно я прочитал «Чистый код» Роберта Мартина, поэтому я буду цитировать эту книгу, когда она уместна.Первое сообщение от Роберта Мартина заключается в том, что комментарий — признак неудачи. Комментарии пишутся только для того, чтобы указать на ошибку программиста, который не мог четко выразить свою идею с помощью языка программирования. Процесс анализа кода — очень широкое понятие, выходящее далеко за рамки данной статьи. Но позвольте мне поделиться с вами уловкой для написания действительно хорошего кода: вы должны написать его так, чтобы его можно было читать, как если бы это были предложения. Объектно-ориентированное программирование намного проще, чем функциональное, широко распространенная практика именования классов существительными и методов с помощью глаголов делает код более естественным.Например, у нас есть кролик, и давайте опишем некоторые из его основных функций, как если бы они были интерфейсом:

 интерфейс RabbitInterface
{
    публичная функция run ();
    публичная функция jump ();
    публичная функция stop ();
    публичная функция hide ();
} 

Мы просто создаем один объект из Rabbit class:

 $ кролик = новый кролик ();
$ rabbit-> запустить ();
$ кролик-> стоп (); 

Код легко читается. Метод run запускает rabbit , метод stop — интуитивно понятная команда, она останавливает предыдущее действие, и кролик останавливается.Теперь давайте научим нашего кролика некоторым трюкам и заставим его пробежать фиксированное расстояние, которое мы передадим в качестве параметра методу run .

 $ кролик-> бег (100); 

И он побежал … Но мы не можем понять, что означает 100. Означает ли это число минуты, метры или футы? Это может быть исправлено с помощью комментария:

 // Кролик должен пробежать 100 метров
$ rabbit-> запустить (100); 

Если кролик начинает «бегать» в нескольких местах и ​​строках вашего кода, к каждому из них требуются дополнительные комментарии.Комментарии будут дублироваться и должны храниться сразу в нескольких местах. Первое, что можно сделать, чтобы избежать комментариев, — это заменить число на переменную.

 $ метров = 100;
$ rabbit-> run ($ метров); 

В данном случае комментарий не нужен, потому что читаемость кода станет немного лучше, и вы увидите, что кролик пробегает по коду 100 метров. Но лучшим вариантом будет добавить контекст к имени метода.

 $ кролик-> runInMetres (100); 

Кролик — существительное, бег, — наречие, в метрах, — контекст, который мы добавляем в метод, чтобы он улавливал суть.По этой схеме можно писать методы.

 $ кролик-> runInSeconds (25);
$ rabbit-> runTillTime (новый \ DateTime ('завтра'));
$ rabbit-> runTillTheEndOfForest ($ sherwood); 

Они охватят суть метода без дополнительных комментариев. Просто дайте своим переменным и методам правильные имена, и вы уменьшите количество ненужных комментариев в своем коде. Роберт Мартин дает хороший совет по этому поводу:

Не тратьте время на написание комментариев, в которых объясняется созданный вами беспорядок, — потратьте его на то, чтобы исправить это.

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

 $ кролик-> runUntilFindVegetables ();
$ rabbit-> runForwardAndTurnBackIfMeet ([$ wolf, $ hunter]); 

Это уже перебор:

 $ rabbit-> runForwardUntilFindCarrotOrCabbageAndTurnBackIfMeetWolfOrHunter (); 

Этот метод плохо читается, неправильная архитектура.Его можно реорганизовать, например, так:

 $ conditions = new Condition ();

$ untilCondition = (новое условие \ До ()) -> findVegetables ('морковь', 'капуста');
$ turnBackCondition = (новое условие \ TurnBack ()) -> ifMeet ('волк', 'охотник');

$ условия-> добавить ($ untilCondition) -> добавить ($ turnBackCondition);
$ rabbit-> run (Направление :: ВПЕРЕД, $ условия); 

Есть также исключения в длине имен методов. Например, когда вы пишете спецификации для phpSpec, у вас может не быть ограничений на длину метода, главное, чтобы ваш код улавливал суть.Вот пример кода из документации phpSpec:

 класс MovieSpec расширяет ObjectBehavior
{
    функция it_should_have_john_smith_in_the_cast_with_a_lead_role ()
    {
        $ this-> getCast () -> shouldHaveKeyWithValue ('leadRole', 'Джон Смит');
    }
} 

В спецификациях подчеркивание используется в именах методов, и так легче читать длинные предложения. Он не соответствует стандарту PSR, в котором используется camelCase , но будет приемлемым для удобочитаемости тестов.

Ощущение надлежащей длины методов придет со временем и опытом. Вы также можете посмотреть примеры из популярных фреймворков и библиотек.

Комментарии характеристики

Устаревший

Очень часто программисты меняют код, но забывают изменить комментарии. Особенно, когда над одним разделом работают несколько программистов. Есть комментарии, но они написаны одним из программистов, а другие не осмеливаются изменять комментарии, написанные другим программистом, либо слишком ленивы для этого, либо просто не обращают внимания.В результате эти старые устаревшие комментарии только запутают новичка. Решение этой проблемы довольно простое. Как вариант, всегда обращайте внимание на актуальность комментариев, но это потребует вашего внимания и усилий. Или просто удалите старые комментарии. Нет комментариев лучше старых устаревших комментариев.

Резервирование

Значит, комментарий излишний и пишется там, где все понятно без комментария. Вот пример кода с дополнительными комментариями:

 // Разрезать морковь на 4 части
$ pieceOfCarrot = $ морковь / 4;
// Пусть кролик съест все кусочки моркови один за другим
foreach ($ pieceOfCarrot as $ pieceOfCarrot) {
    $ rabbit-> съесть ($ pieceOfCarrot); // Кролик ест морковь
} 

Если мы удалим комментарии, код останется чистым:

 $ штук моркови = $ морковь / 4;
foreach ($ pieceOfCarrot as $ pieceOfCarrot) {
    $ rabbit-> съесть ($ pieceOfCarrot);
} 

Незавершенность

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

 общественное мероприятие есть ($ food)
{
    switch ($ food) {
        футляр 'морковь':
            $ this-> getCalories (50);
            перерыв;
        чехол 'капуста':
            $ this-> getCalories (100);
            перерыв;
        дефолт:
            // Если кролик съест неизвестную еду - он погибнет :(
            перерыв;
    }
} 

Что означает комментарий «кролик умрет»? Понятно, когда это происходит в реальной жизни.А что с программой? Что хотел делать автор после этого? Освободить память, занятую кроликом? Чтобы упомянуть исключение, а затем закончить его в другом фрагменте кода? В этом коде с кроликом ничего не происходит, кролик просто не получает новых калорий, когда ест что-нибудь, кроме моркови и капусты. Но для новичка, который будет дорабатывать код, авторская идея останется непонятной. Вполне вероятно, что новичок удалит комментарий и сделает его по-своему.

Недостоверность

Все люди могут ошибаться.Но программисты вносят их не только в код, но и в блоки комментариев. Из-за невнимательности, усталости или незнания иностранного языка комментарии запутываются и сбивают с толку других. К сожалению, бывает. Единственный совет, который я могу вам дать, — это нести ответственность за свои комментарии. Если вы решили что-то написать, пишите правильно. При написании комментариев вы должны быть перфекционистом.

Неочевидность

Когда в определенной части кода используются неизвестные или неочевидные термины.

 // Использует коэффициент роста кролика в день, который зависит от нескольких факторов
$ rabbit-> growInSize (); 

Здесь мы видим, что рост кролика определяется некоторым показателем, который зависит от некоторых факторов. В этом фрагменте кода неясно, что такое индекс роста кролика и как мы можем его вычислить. Лучше убрать этот комментарий и поставить более подробный после функции.

Значит, мы вообще не должны писать комментарии, не так ли?

Мы должны их написать, но мы должны нести за них ответственность.Бывают ответственные моменты, когда они необходимы.

Информационная ценность

Кое-где комментарии требуются. Когда необходимо объяснить алгоритм или когда группе программистов пришлось использовать «хаки» в коде и оставить комментарий по этому поводу. Чтобы описать причину, по которой это было сделано, о чем идет речь и когда его нужно исправить. Но вы должны попытаться выбрать правильные имена для ваших переменных и методов.

От регулярных выражений я оцепенел, и мне приходится тратить много времени, чтобы их понять.В этом случае информативность не будет лишней.

 // Найдите всех кроликов в местах,
// конец на: поле, поле, лес
// начинается: желтый, зеленый
// и не чувствительны к регистру
// например Блэкшир, Гринфилд, Шервуд, ШЕРВУД, дерево, Йеллоустон
$ locationRegExp = '/ \ b (желтый | зеленый) \ w * | \ w * (шир | поле | лес) \ b / i';
$ rabbits = $ search-> findRabbitsInLocations (locationsRegExp); 

Намерения

Есть много способов решить одну и ту же задачу в программировании. У каждого программиста свой стиль программирования, поэтому ему бывает сложно сканировать код, написанный кем-то другим.Если вы предпочитаете определенный стиль программирования или на практике знаете, что используемые вами алгоритмы трудно читать, поместите текст справки перед сложным фрагментом кода.

Уведомления и предупреждения

В некоторых случаях вы не можете использовать определенную функцию, например:

• необходимое расширение не было установлено в производственной среде или поставщик не был обновлен;
• для выполнения одной из функций требуется слишком много времени и лучше не запускать ее;
• из-за высоких требований к ресурсам вы не можете выполнить цикл больше определенного количества раз.

Если вы столкнетесь с такой ситуацией, комментарии будут вам очень полезны.

Прирост

Когда определенная строка кода настолько важна, что вам нужно уделять ей особое внимание. Однажды я столкнулся с проблемой, когда кодирование многобайтовых функций не было настроено на постановку, и потратил много времени на поиск и решение этой проблемы. Когда проблема была решена, я добавил в свой код руководство по параметрам с комментарием, объясняющим, почему я это сделал:

 // Установите кодировку по умолчанию для функций MB вручную, чтобы предотвратить случаи, когда она пропущена в конфигурации
mb_internal_encoding ('UTF-8'); 

Еще один совет от Дина Мартина:

Не комментируйте плохой код — перепишите его.

Когда вы сталкиваетесь с непонятным кодом и потратили много времени, пытаясь его понять, а затем оставляете несколько комментариев для следующего разработчика, вы должны понимать, что код не станет лучше. В этой ситуации, если вы понимаете код, попробуйте провести его рефакторинг, чтобы сделать его более читабельным. Девиз бойскаута: «Оставьте палаточный лагерь (код) чище, чем вы его нашли».

Оформление документации с помощью doc.blocks

Существует отдельный вид комментариев PHP, который имеет свой собственный стандарт — он называется DocBlock).Существует инструмент phpDocumentor (также известный как phpDoc) для обработки блоков документов. Он может читать докблоки из кода и создавать на их основе документацию. DocBlock — это комбинация DocComment и размещенных в нем описаний на основе стандарта PHPDoc. Поддерживается многострочный комментарий типа C (DocComment):

 / *
 * Это
 * комментарий в стиле C в PHP
 * / 

DocBlock выделяется дополнительной звездочкой / ** в начале комментария.

 / **
 * Это
 * документ PHP
 * / 

DocBlock может иметь только одну строку, но, тем не менее, он должен начинаться с / ** .

 / ** Это тоже докблок * / 

Стандарт PHP Doc для ДОКУМЕНТАЦИИ КОДА PHP основан на javaDoc для Java. Важным компонентом Docbloc являются теги и аннотации, которые делают комментарии семантическими. Например, тег или аннотации начинаются с @ .

 / **
 * Вход по электронной почте и паролю
 *
 * @param Request $ request Запрос
 *
 * @return Ответ
 *
 * @throws BadRequestHttpException
 * @throws UnauthorizedHttpException
 *
 * @Rest \ Post ("/ вход")
 * /
общедоступная функция loginAction (запрос $ request)
{
} 

В приведенном выше примере @param , @return и @throws являются тегами PHPDoc, и они будут проанализированы с помощью phpDocrumentor. @Rest \ Post ("/ login") — это аннотация к FOSRestBundle. Разница между аннотациями и тегами заключается в том, что теги документируют только код PHP, а аннотации добавляют или изменяют код. Отличительной особенностью аннотаций PHP по сравнению с аннотациями Java является то, что аннотации Java являются частью Java, а аннотации PHP являются комментариями, и для их использования вы должны использовать отражение. Возможно, в будущем аннотации станут частью PHP, но в настоящее время для их чтения вам следует использовать этот парсер. Также стоит отметить, что если мы изменим начало док-блока с / ** на / * , он не будет док-блоком, даже если он содержит теги или аннотации, и синтаксический анализатор проигнорирует его.

Док-блоки

настолько широко используются в сообществе программистов PHP, что PSR-5 (стандартная рекомендация PHP) готовится на основе док-блоков. Когда я писал эту статью, это был черновик.

В PHP с помощью док-блоков можно задокументировать следующие элементы:

• функций;
• конктантов;
• классов;
• интерфейсов;
• черт;
• констант класса;
• объектов недвижимости;
• методов.

Также важно, чтобы каждый док-блок можно было применить только к одному элементу конструкции. Это означает, что у каждой функции, переменной и класса есть собственный док-блок.

 / **
 * Класс кролика
 *
 * @ версия 0.1.0
 * /
класс Rabbit реализует RabbitInterface
{
    const STATUS_RUNNING = 'работает';

    / **
     * @var string $ status Статус
     * /
    частный статус $;

    / **
     * Установить статус "бег" для кролика
     *
     * @return $ this
     * /
    публичная функция run ()
    {
        $ this-> status = self :: STATUS_RUNNING;

        вернуть $ this;
    }
} 

В PHPDoc много тегов, но не все теги можно применить ко всем элементам структуры.Ниже приведен список уже существующих тегов, их использование и объяснение.

• @api (method) определяет стабильные общедоступные методы, семантика которых не изменится до следующего основного выпуска.
• @author (в любом месте) определяет имя или адрес электронной почты автора, написавшего следующий код.
• @copyright (в любом месте) используется для обозначения ваших авторских прав в коде.
• @deprecated (в любом месте) — полезный тег, который означает, что этот элемент исчезнет в следующих версиях.Обычно вместо кода есть комментарий. Кроме того, в большинстве IDE выделяются места, где используются старые методы. Когда необходимо очистить устаревший код для новой версии, поиск по этому тегу будет проще.
• @example (в любом месте) используется для вставки ссылки на файл или веб-страницу, где показан пример использования кода. В настоящее время phpDocumentor утверждает, что этот тег не полностью поддерживается.
• @filesource (file) — это тег, который вы можете разместить только в самом начале php файла, потому что вы можете применить этот тег только к файлу и включить весь код в сгенерированную документацию.
• @global (переменная) — на данный момент этот тег не поддерживается, возможно, он будет реализован в следующих версиях при его обновлении и переработке.
• @ignore (в любом месте) — док-блок с этим тегом не будет обрабатываться при создании документации, даже если есть другие теги.
• @internal (в любом месте) — часто используется с тегом @api, чтобы показать, что код используется внутренней логикой этой части программы. Элемент с этим тегом не будет включен в документацию.
• @license (файл, класс) показывает тип лицензии написанного кода.
• @link (в любом месте) используется для добавления ссылок, но согласно документации этот тег не полностью поддерживается.
• @method (class) применяется к классу и описывает методы, обрабатываемые функцией __call () .
• @package (файл, класс) делит код на логические подгруппы. Когда вы помещаете классы в одно и то же пространство имен, вы указываете на их функциональное сходство.Если классы принадлежат к разным пространствам имен, но имеют одинаковые логические характеристики, они могут быть сгруппированы с помощью этого тега (например, это относится к классам, которые все работают с тележкой покупателя, но принадлежат к разным пространствам имен). Но лучше избегать такой ситуации. Например, стиль кода Symfony не использует этот тег.
• @param (метод, функция) описывает входящие параметры функции. Стоит отметить, что если вы описываете входящие параметры для определенной функции с помощью док-блоков, вы должны описывать все параметры, а не только один или два.
• @property (class) — как и @method этот тег помещается в док-блок класса, но его функция — описывать свойства, к которым осуществляется доступ с помощью магических функций __get () и __set () .
• @ property-read, @ property-write (class) аналогичны предыдущему тегу, но обрабатывают только один магический метод __get () или __set () .
• @return (метод, функция) используется для описания значения, возвращаемого функцией.Вы можете указать его тип, и PhpStorm выберет его и даст вам разные советы, но давайте поговорим об этом позже.
• @see (в любом месте) — с помощью этого тега вы можете вставлять ссылки на внешние ресурсы (как и в случае с @link ), но также позволяет размещать относительные ссылки на классы и методы.
• @since (в любом месте) — можно указать версию, в которой появился кусок кода.
• @source (в любом месте, кроме начала) — с помощью этого тега вы можете размещать в документации куски исходного кода (вы задаете начало и конец строки кода)
• @throws (функция метода) используется для указания исключений, которые могут быть вызваны этой функцией.
• @todo (в любом месте) — наиболее оптимистичный тег, используемый программистами как напоминание о том, что нужно сделать в определенном фрагменте кода. В IDE есть возможность обнаруживать этот тег и группировать все части кода в отдельном окне, что очень удобно для дальнейшего поиска. Это рабочий стандарт, который используется очень часто.
• @uses (в любом месте) используется для отображения связи между различными частями кода. Он похож на @see .Разница в том, что @see создает однонаправленную ссылку, и после перехода на новую страницу документации у вас не будет обратной ссылки, а @uses предоставит вам ссылку для обратной навигации.
• @var (переменная) используется для указания и описания переменных, аналогичных тем, которые используются внутри функций и для свойств класса. Следует различать этот тег и @param . Тег @param используется только в док-блоках для функций и описывает входящие параметры, а @var используется для описания переменных.
• @version (в любом месте) обозначает текущую версию программы, в которой появляется этот класс, метод и т. Д.

Устаревшие теги, которые, скорее всего, не будут поддерживаться в будущем:

• @category (файл, класс) использовался для группировки пакетов вместе.
• @subpackage (файл, класс) использовался для обозначения определенных групп в пакете.

Не все теги одинаково популярны. @var, @param, @return, @todo, @throws наиболее широко используются.Остальные менее популярны. А таких тегов, как @property и @method я не встречал, потому что работать с магией опасно!

Простота использования док-блоков в IDE

Если вы разрабатываете проект с открытым исходным кодом, конечно, необходимо задокументировать общедоступный API с помощью док-блоков. Это не только дает вам возможность создавать окончательную документацию, но также позволяет другим программистам с комфортом использовать ваш код в своей среде IDE. Что касается вашего частного кода для аутсорсингового проекта, использование док-блоков может показаться немного неуместным, но в любом случае я советую вам использовать их, потому что они ускорят вашу разработку.

Возьмем самую популярную PHP IDE для PHP — PhpStorm. И посмотрите на предыдущий пример поиска кролика:

 $ кроликов = $ search-> findRabbitsInLocations ('/ Sherwood /');
foreach ($ кролики как $ кролик) {
    $ rabbit-> doSomething ();
} 

Что означают переменные $ кролики и $ кролик ? PhpStorm ничего об этом не знает. PHP слабо типизирован, и тип результата функции строго не указан в описании (привет, PHP 7, где он будет реализован).Вот почему вы должны указать своей среде IDE, как работать с определенными частями кода с помощью док-блоков. Есть несколько вариантов. Можно так:

 / ** @var Rabbit $ rabbit * /
foreach ($ кролики как $ кролик) {
    $ rabbit-> doSomething ();
} 

Или добавьте тег @return в метод findRabbitsInLocations :

 / **
 * @return Rabbit []
 * /
общедоступная функция findRabbitsInLocations ($ location)
{
    // здесь какие-то операции ...
    возвращение [];
} 

Обратите внимание, что мы указываем Rabbit [] , а не Rabbit .Скобки поясняют, что возвращается массив объектов класса. Если мы уберем скобки, это означает, что метод возвращает один пример класса Rabbit. Вы также можете написать это так: @return null | Rabbit [] , вертикальная палка означает OR, в этом случае мы указываем, что метод вернет массив кроликов или null .

Независимо от того, какой способ указать тип вы выбрали, теперь PHPStorm покажет вам несколько подсказок и подсказок после того, как вы наберете $ rabbit-> и немного подождете.

Это происходит потому, что PHPStorm знает, что в $ rabbits переменная возвращается массивом объектов Rabbit . Затем в foreach cycle $ rabbit переменная получает один элемент массива, который является примером класса Rabbit , а PHPStorm показывает вам все доступные общедоступные методы из этого класса. Таким образом, вы можете использовать классы с общедоступными методами, написанными вашими коллегами, не отрывая рук от клавиатуры.

PHPStorm предоставит вам подсказки, и если у метода есть понятное имя, вы сможете использовать его, даже не читая исходный код и документацию.

Еще одна полезная функция, доступная вам при использовании док-блоков с PHPStorm, — это предупреждения о неправильных параметрах доступа. Закончим писать док-блок для одного из методов класса Rabbit :

 / **
 * Пробег в метрах
 *
 * @param int $ meter Метры
 * /
публичная функция runInMetres ($ meter)
{
    // здесь некоторые операции...
} 

Здесь мы указываем, что мы должны использовать целое число для доступа (в PHP 7 можно будет установить число с помощью синтаксиса). Что будет, если мы передадим в этот метод массив?

PHPStorm выделяет это и дает намек на то, что int здесь исключено, когда вы используете массив . Очень удобно, правда? Подсказки также будут отображаться для несовпадающих классов и интерфейсов. Если ваш метод поддерживает несколько типов входящих аргументов, разделите их с помощью |.В этом примере, если метод runInMetres () может работать с массивами, вы можете написать @param int | array $ meter Meters , и докблок перестанет показывать предупреждения.

PhpStorm также может генерировать док-блоки. Поместите курсор в строку над объявлением функции, класса или переменной, введите / ** и нажмите Введите . IDE сгенерирует шаблон док-блока, который вы можете немного изменить, если хотите. Вы также можете запустить создание док-блока, используя Alt + Insert.

Как следовать стилям комментирования

Хорошо, если все члены команды соблюдают правила комментирования PHPDoc.Но на практике это случается редко. Стандарта придерживаются только перфекционисты, а также те, кто давно пользуется док-блоками, и это вошло для них в привычку. Некоторые начинающие программисты хотят использовать док-блоки, но иногда забывают их использовать или не полностью понимают теги. Конечно, есть крепкие орешки, которые не используют док-блоки, даже если команда их использует.

Чтобы уменьшить дискомфорт, каждый член команды должен включить проверку док-блоков в PhpStorm: Настройки> Редактор> Инспекции> PHPDoc и отметить все флажки:

Конечно, всех соблюдать правила нельзя.Для самых ленивых я хочу еще раз дать совет из «Чистого кода» (речь идет о форматировании кода, но последствия те же):

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

Создание документации с помощью phpDocumentor

Теперь, когда все следуют правилам и ваш код полон док-блоков, вы можете сгенерировать документацию.Я много пишу о документации phpDocumentor, показываю только самые необходимые команды, другие рекомендации по документированию php-кода вы можете найти на официальном сайте.

Итак, вам нужно установить phpDocumentor. Его можно установить глобально следующим образом:

 $ wget http://www.phpdoc.org/phpDocumentor.phar
$ chmod + x phpDocumentor.phar
$ sudo mv phpDocumentor.phar / usr / локальный / bin / phpdoc
$ phpdoc - версия 

Или добавьте его как требование к composer.json вашего проекта.

 $ composer require --dev "phpdocumentor / phpdocumentor: 2. *" 

И теперь, когда вы находитесь в каталоге проекта, который заполнен док-блоками, просто запустите его с консоли.

 $ phpdoc -d src / 

Как я уже упоминал, это самый необходимый набор опций для генерации документации, опция -d src / показывает путь к файлам, с которыми вы хотите работать. Сгенерированная информация будет находиться в папке с именем output .Конечно, у этой утилиты разные характеристики и множество функций. Вот пример кода PHPDocumentor, и вы можете выбрать уже существующий шаблон или создать свой собственный.

Создание документации с помощью Sami

O Еще один инструмент для документирования PHP на основе док-блоков — это утилита Sami. Возможно, это не так популярно, но я решил упомянуть об этом, потому что документация Symfony создается с использованием Sami. И Fabien Potencier, создавший эту утилиту, упоминает об этом в своем блоге.

Генератор документации Sami отличается от phpDocumentor тем, что его конфигурация хранится в файлах PHP. В общем, у него больше возможностей для настройки, чем у phpDocumentor, но вам придется настраивать все это вручную, другими словами, писать код. Вы даже можете переопределить различные фрагменты кода, которые отвечают за создание документации. Все необходимые шаблоны можно найти на TWIG, плюс их легко переопределить. Для получения более подробной информации о Сами перейдите на страницу GitHub.

PHPDoc комментарии | PhpStorm

Для комментариев к документации PhpStorm предоставляет автозавершение, которое включено по умолчанию. PhpStorm создает заглушки блоков PHPDoc, когда вы вводите открывающий тег / ** и нажимаете , вводите или нажимаете Alt + Insert и назначаете конструкцию кода (класс, метод, функцию и т. Д.) Для документ. В зависимости от вашего выбора PhpStorm создаст необходимые теги или добавит пустую заглушку документации.

Если вам нужны дополнительные теги, специфичные для PHP, PhpStorm обеспечивает автозавершение кода, которое предлагает имена тегов, релевантные в текущем контексте.Если определенный тег имеет несколько значений, завершение кода предоставляет список доступных значений.

В комментариях PHPDoc PhpStorm поддерживает параметры форматирования в соответствии с ZEND, PEAR и другими стандартами кодирования.

Комментарии PHPDoc в исходном коде доступны для быстрого поиска в документации, который помогает быстро получить информацию для любого задокументированного символа. Вы можете открыть их для просмотра в окне инструмента документации, нажав Ctrl + Q .

Включить комментарии к документации

1. Нажмите Ctrl + Alt + S , чтобы открыть настройки IDE и выбрать Editor | Общие | Умные ключи.

2. В разделе «Ввод» установите или снимите флажок «Вставить заглушку комментария к документации».

Создание блока PHPDoc для конструкции кода

1. Чтобы вызвать создание блока PHPDoc, выполните одно из следующих действий:

   • Поместите курсор перед требуемой конструкцией кода (класс, метод, функция и так далее), введите комментарий к открывающему блоку / ** и нажмите Введите .

   • В контекстном меню редактора выберите конструкцию кода, для которой будут созданы комментарии PHPDoc.

   • Нажмите Alt + Insert , затем выберите «Создать блоки PHPDoc» и выберите конструкцию кода, для которой будут созданы комментарии PHPDoc.

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

2. Опишите перечисленные параметры и, при необходимости, возвращайте значения. PhpStorm проверяет и обрабатывает синтаксис в комментариях в соответствии с настройками проверки кода.

Создание тегов в блоке комментариев PHPDoc

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

1. В блоке PHPDoc выберите нужную пустую строку и нажмите Ctrl + Пробел .

2. Выберите соответствующий тег из списка предложений.

3. Если введенный тег имеет несколько значений, нажмите Ctrl + Пробел и выберите нужное значение из списка предложений.

Настройте форматирование внутри комментариев PHPDoc

Вы можете настроить внешний вид комментариев PHPDoc, представление имен классов и порядок сортировки тегов по умолчанию. Обратите внимание, что тег свойств больше не настраивается, тег @var по умолчанию вставляется автоматически. Подробнее см. Https://github.com/phpDocumentor/fig-standards/pull/55.

1. В диалоговом окне «Настройки / Предпочтения» Ctrl + Alt + S перейдите к.

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

3. Укажите, как вы хотите, чтобы PhpStorm представлял имена классов для свойств, параметров функций, возвращаемых и генерируемых значений и т. Д., Установив или сняв флажок Использовать полностью определенные имена классов.

4. При необходимости определите способ сортировки сгенерированных тегов PHPDoc, установив флажок «Сортировать теги PHPDoc».

   Теги PHPDoc, которые не добавлены в список, генерируются под перечисленными.

Использование проверок кода PHPDoc

PhpStorm предоставляет набор предопределенных проверок кода, нацеленных на блоки PHPDoc. Эти проверки проверяют, поставляются ли классы, методы, функции, переменные и константы с комментарием PHPDoc и соответствуют ли теги в комментарии документированному элементу.

Включение или отключение проверки PHPDoc

1. В диалоговом окне «Настройки / Предпочтения» Ctrl + Alt + S выберите.

2. На открывшейся странице Inspections разверните узел PHPDoc в разделе PHP.

3. В открывшемся списке предопределенных проверок включите или отключите проверку, установив или сняв флажок рядом с ней.

Убедитесь, что комментарии PHPDoc предоставлены для конструкций кода определенного типа.

1. Включите проверку отсутствия комментариев PHPDoc.

2. В области «Параметры» установите флажки рядом с нужным типом элемента: класс, метод, функция, переменная или константа.

   Чтобы подавить сообщение об ошибке «Отсутствует комментарий PHPDoc», если метод или функция не содержит никаких параметров или возвращаемых значений, установите флажок «Игнорировать PHPDoc без @ param / @ return».

Последнее изменение: 8 марта 2021 г.

PHP | Sentry Documentation

На этой странице мы познакомим вас с PHP SDK от Sentry, автоматически сообщая об ошибках и исключениях в вашем приложении.

Если у вас еще нет учетной записи и установленного проекта Sentry, отправляйтесь к часовой.io, затем вернитесь на эту страницу.

Используете фреймворк? Взгляните на наши специальные руководства, чтобы начать работу.

Sentry PHP SDK обеспечивает поддержку PHP 7.2 или новее.

Установить

Sentry собирает данные с помощью SDK во время выполнения вашего приложения. Они зависят от платформы и позволяют Sentry глубоко понимать, как работает ваше приложение.

Чтобы установить PHP SDK, вам необходимо использовать Composer в своем проекте. Дополнительные сведения о Composer см. В документации Composer.

Bash

Скопировано

  composer require sentry / sdk  

Настроить

После того, как вы завершите настройку проекта в Sentry, Sentry выдаст вам значение, которое мы называем DSN или именем источника данных. Он очень похож на стандартный URL, но это просто представление конфигурации, необходимой для Sentry SDK. Он состоит из нескольких частей, включая протокол, открытый ключ, адрес сервера и идентификатор проекта.

Чтобы зафиксировать все ошибки, даже те, которые возникли во время запуска вашего приложения, вы должны как можно скорее инициализировать Sentry PHP SDK.

PHP

Скопировано

  \ Sentry \ init (['dsn' => 'https: //[email protected]/0']);  

Использование

В PHP вы можете либо перехватить перехваченное исключение, либо перехватить последнюю ошибку с помощью captureLastError.

PHP

Скопировано

  попробовать {
    $ this-> functionFailsForSure ();
} catch (\ Throwable $ exception) {
    \ Sentry \ captureException (исключение $);
}



\ Sentry \ captureLastError ();  

Мониторинг производительности

Просто установите для traces_sample_rate значение больше 0.0 после этого будет включен мониторинг производительности.

PHP

Скопировано

  \ Sentry \ init ([
  'dsn' => 'https: //[email protected]/0',
  'traces_sample_rate' => 1.0
]);  

Данные о производительности передаются с использованием нового типа событий, называемого «транзакции», о котором вы можете узнать в Распределенной трассировке. Для захвата транзакций необходимо установить и настроить SDK, чтобы установить для параметра traces_sample_rate ненулевое значение. В приведенном выше примере конфигурации передается 100% захваченных трасс. Обязательно уменьшите это значение в производственной среде, иначе вы можете быстро израсходовать свою квоту.

Подробнее о выборке см. В разделе Использование SDK для фильтрации событий.

Следующие шаги

• Конфигурация

  Дополнительные параметры конфигурации для SDK.

• Использование

  Используйте SDK, чтобы вручную фиксировать ошибки и другие события.

• Интеграции

  Узнайте об автоматических интеграциях, которые предоставляет Sentry, и о том, как их настроить.

• Устранение неполадок

  Действия по устранению неполадок для PHP

• Производительность

  Настройте нашу интеграцию мониторинга производительности в соответствии с потребностями вашей организации. Вы можете использовать домашнюю страницу мониторинга производительности для поиска или просмотра данных транзакций.

• Расширяющие события

  Обогащайте события дополнительным контекстом, чтобы упростить отладку.

• Управление данными

  Управляйте своими событиями путем предварительной фильтрации, очистки конфиденциальной информации и ее пересылки в другие системы.

Помогите улучшить этот контент
Наша документация имеет открытый исходный код и доступна на GitHub. Ваш вклад приветствуется, будь то исправление опечатки (черт возьми!) Или предложение обновления («да, это было бы лучше»).

Elasticsearch-PHP [7.x] | Резинка

Документы

Обзор »

• PHP API: master7.x (текущая) другие версии другие версии: master7.x (текущая) 6.x5.x2.x1.x0.4
• Обзор
  • DSL сообщества
  • Сообщество интеграции
  • Критические изменения по сравнению с 6.x
• Установка
• Подключение
• Конфигурация
  • Работа с массивами и объектами JSON в PHP
  • Конфигурация хоста
  • Установить повторные попытки
  • HTTP метаданные
  • Включение регистратора
  • Настроить обработчик HTTP
  • Пространства имен
  • Пул подключений
  • Селекторы
  • Сериализаторы
  • Настройка настраиваемой фабрики подключений
  • Установить закрытие конечной точки
  • Конфигурация по запросу
  • Future Mode (Режим будущего)
• Операции
  • Операции управления индексами
  • Поисковые операции
  • Индексирование документов
  • Получение документов
  • Обновление документов
  • Удаление документов
• Ссылка — Конечные точки
  • Elasticsearch \ Клиент
  • Elasticsearch \ ClientBuilder
  • Elasticsearch \ Namespaces \ AsyncSearchNamespace
  • Elasticsearch \ Namespaces \ AutoscalingNamespace
  • Elasticsearch \ Namespaces \ CatNamespace
  • Elasticsearch \ Namespaces \ CcrNamespace
  • Elasticsearch \ Namespaces \ ClusterNamespace
  • Elasticsearch \ Namespaces \ DanglingIndicesNamespace
  • Elasticsearch \ Namespaces \ DataFrameTransformDeprecatedNamespace
  • Elasticsearch \ Namespaces \ EnrichNamespace
  • Elasticsearch \ Namespaces \ EqlNamespace
  • Elasticsearch \ Namespaces \ FeaturesNamespace
  • Elasticsearch \ Namespaces \ GraphNamespace
  • Elasticsearch \ Namespaces \ IlmNamespace
  • Elasticsearch \ Namespaces \ IndicesNamespace
  • Elasticsearch \ Namespaces \ IngestNamespace
  • Elasticsearch \ Namespaces \ LicenseNamespace
  • Elasticsearch \ Namespaces \ LogstashNamespace
  • Elasticsearch \ Namespaces \ MigrationNamespace
  • Elasticsearch \ Namespaces \ MlNamespace
  • Elasticsearch \ Namespaces \ MonitoringNamespace
  • Elasticsearch \ Namespaces \ NodesNamespace
  • Elasticsearch \ Namespaces \ RollupNamespace
  • Elasticsearch \ Namespaces \ SearchableSnapshotsNamespace
  • Elasticsearch \ Namespaces \ SecurityNamespace
  • Elasticsearch \ Namespaces \ SlmNamespace
  • Elasticsearch \ Namespaces \ SnapshotNamespace
  • Elasticsearch \ Namespaces \ SqlNamespace
  • Elasticsearch \ Namespaces \ SslNamespace
  • Elasticsearch \ Namespaces \ TasksNamespace
  • Elasticsearch \ Namespaces \ TextStructureNamespace
  • Elasticsearch \ Namespaces \ TransformNamespace
  • Elasticsearch \ Namespaces \ WatcherNamespace
  • Elasticsearch \ Namespaces \ XpackNamespace
• Помощники клиентов
• Примечания к выпуску

Обзор »

САМОЕ ПОПУЛЯРНОЕ

• Начало работы с Elasticsearch: видео
• Введение в кибану: видео
• ELK для журналов и показателей: видео

PHP Быстрый старт | Google Docs API | Разработчики Google

Выполните шаги, описанные на оставшейся части этой страницы, чтобы создать простой PHP
приложение командной строки, которое делает запросы к Google Docs API.

Предварительные требования

Для запуска этого краткого руководства необходимы следующие предварительные условия:

• PHP 5.4 или выше с интерфейсом командной строки (CLI) и расширением JSON
  установлено
• Инструмент управления зависимостями Composer
• Проект Google Cloud Platform с включенным API. Создать проект и
  включить API, см.
  Создайте проект и включите API

Примечание. В этом кратком руководстве вы включаете «Google Docs API».2,0

Посмотреть установку библиотеки
страница для альтернативы
варианты установки.

Шаг 2: Настройте образец

Создайте файл с именем quickstart.php в своем рабочем каталоге и скопируйте его в
следующий код:

Шаг 3. Запустите образец

Запустите образец, используя следующую команду:

  PHP quickstart.php 
 

При первом запуске образца вам будет предложено авторизовать доступ:

1. Перейдите по указанному URL-адресу в своем веб-браузере.

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

2. Нажмите кнопку Принять .
3. Скопируйте предоставленный код, вставьте его в командную строку и нажмите
   Введите .

Банкноты

• Информация авторизации хранится в файловой системе, поэтому последующие
  казни не требуют авторизации.
• Процесс авторизации в этом примере разработан для командной строки.
  заявление. Для получения информации о том, как выполнить авторизацию в сети
  приложение, см.
  Использование OAuth 2.0 для приложений веб-сервера.

Поиск и устранение неисправностей

В этом разделе описаны некоторые общие проблемы, с которыми вы можете столкнуться при
пытается запустить это краткое руководство и предлагает возможные решения.

Проблема с сертификатом SSL: невозможно получить сертификат местного эмитента

Эта ошибка указывает на то, что нижележащие библиотеки HTTP не могут найти сертификат.
store, и поэтому не могут установить SSL-соединение с серверами Google.См. Документацию библиотеки Guzzle
для получения информации о том, как настроить хранилище сертификатов на вашем компьютере.

Uncaught InvalidArgumentException: отсутствует необходимый URI перенаправления

Эта ошибка возникает, если используемый файл credentials.json содержит клиента
ID неправильного типа. Для этого кода требуется идентификатор клиента OAuth типа Другое ,
который будет создан для вас при использовании кнопки на шаге 1. Если вы создаете свой
собственный идентификатор клиента, убедитесь, что вы выбрали правильный тип.

Это приложение не проверено

Если на экране согласия OAuth отображается предупреждение
«Это приложение не подтверждено», ваше приложение запрашивает области, которые предоставляют
доступ к конфиденциальным данным пользователя. Если ваше приложение использует чувствительные области, ваш
ваше приложение должно пройти процесс проверки
чтобы удалить это предупреждение и другие ограничения. На этапе разработки вы можете
продолжить после этого предупреждения, нажав
Advanced> Перейти к {Project Name} (небезопасно) .

Дополнительная литература

Xdebug: Документация »Все настройки

Настраивает файл журнала Xdebug.

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

Включите эту функцию, задав в качестве значения абсолютный путь. Убедись
что системный пользователь, на котором работает PHP (например, www-data , если вы
работает с Apache) может создавать и записывать в файл.

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

Файл журнала будет включать любую попытку Xdebug
делает для подключения к IDE:

[2693358] Журнал открыт 2020-09-02 07:19: 09.616195
[2693358] [Step Debug] ИНФОРМАЦИЯ: Подключение к настроенному адресу / порту: localhost: 9003.
[2693358] [Step Debug] ERR: не удалось подключиться к клиенту отладки. Пробовал: localhost: 9003 (через xdebug.client_host / xdebug.client_port) :-(
[2693358] [Profiler] ERR: Не удалось открыть файл '/foo/cachegrind.out.2693358'.
[2693358] [Профайлер] ПРЕДУПРЕЖДЕНИЕ: / foo: такого файла или каталога нет
[2693358] [Трассировка] ОШИБКА: Файл '/ foo / trace.1485761369 'не удалось открыть.
[2693358] [Трассировка] ПРЕДУПРЕЖДЕНИЕ: / foo: такого файла или каталога нет
[2693358] Запись закрыта 02.09.2020, 07:19: 09.617510
 

Включает время открытия ( 2020-09-02 07: 19: 09.616195 ),
IP / имя хоста и порт, к которому Xdebug пытается подключиться
( localhost: 9003 ), и удалось ли ( Подключено к
клиент :-) ). Число в скобках ( [2693358] ) — это
Идентификатор процесса.

Включает:

[2693358]

ID процесса в скобках

02.09.2020 07:19:09.616195

время открытия

Для пошаговой отладки:

ИНФОРМАЦИЯ: Подключение к настроенному адресу / порту: localhost: 9003.
ОШИБКА: не удалось подключиться к клиенту отладки. Пробовал: localhost: 9003 (через xdebug.client_host / xdebug.client_port) :-(
 

Для профилирования:

ОШИБКА: не удалось открыть файл '/foo/cachegrind.out.2693358'.
ПРЕДУПРЕЖДЕНИЕ: / foo: нет такого файла или каталога
 

Для трассировки функции:

ОШИБКА: Файл '/ foo / trace.1485761369 'не удалось открыть.
ПРЕДУПРЕЖДЕНИЕ: / foo: нет такого файла или каталога
 

Все предупреждения и ошибки описаны на странице «Описание ошибок» с
подробные инструкции по устранению проблемы, если это возможно. Все ошибки всегда регистрируются
Внутренний механизм ведения журнала PHP (настроен с помощью error_log
в php.ini ). Все предупреждения и ошибки также отображаются в
журнал диагностики, который можно просмотреть, вызвав xdebug_info ().

Связь с пошаговым отладчиком

Журнал отладки также может регистрировать обмен данными между Xdebug и IDE.Это сообщение осуществляется в XML и начинается с XML.
элемент:

Атрибут fileuri перечисляет точку входа вашего
приложение, которое может быть полезно сравнить с breakpoint_set
команды, чтобы увидеть, правильно ли настроены сопоставления путей.

Помимо элемента , вы найдете конфигурацию
особенности:

<- набор_функций -i 4 -n расширенные_свойства -v 1
-> <ответ
       xmlns = "urn: debugger_protocol_v1" xmlns: xdebug = "https: // xdebug.org / dbgp / xdebug "
       command = "feature_set" transaction_id = "4" feature = "extended_properties" success = "1">
   
 

И команды продолжения:

<- step_into -i 9
-> <ответ
       xmlns = "urn: debugger_protocol_v1" xmlns: xdebug = "https://xdebug.org/dbgp/xdebug"
       command = "step_into" transaction_id = "9"
       status = "break" cause = "ok">
           
           
   
 

Вы можете прочитать о DBGP - общей спецификации протокола отладчика на специальной странице документации.

Параметр xdebug.log_level управляет объемом информации.
зарегистрирован.

Многие дистрибутивы Linux теперь используют systemd, который
реализует частных tmp каталогов. Это означает, что когда PHP
запускается через веб-сервер или как PHP-FPM, каталог / tmp
с префиксом, похожим на:

/tmp/systemd-private-ea3cfa882b4e478993e1994033fc5feb-apache.service-FfWZRg
 

Этот параметр можно дополнительно настроить через
XDEBUG_CONFIG
переменная окружения.

Обязательные настройки PHP | Руководство разработчика Adobe Commerce

В этом разделе обсуждается, как установить необходимые параметры PHP.

См. Системные требования для поддерживаемых версий PHP.

Убедитесь, что PHP установлен

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

Если установлен PHP, отображается сообщение, подобное следующему:

  
 
 
 
 
 1
2
3
 
 PHP 7.4.0 (cli) (построено: 14 августа 2019 16:42:46) (NTS)
Авторские права (c) 1997-2018 Группа PHP
Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies с Zend OPcache v7.1.6, Copyright (c) 1999-2018, Zend Technologies
 
 
 Magento 2.4 совместим с PHP 7.3, но мы тестируем и рекомендуем использовать PHP 7.4.
 Если PHP не установлен или требуется обновление версии, установите его, следуя инструкциям для вашего конкретного варианта Linux.В CentOS могут потребоваться дополнительные действия.
 Проверить установленные расширения 
 Magento требует установки набора расширений.
 Magento с открытым исходным кодом:
 ext-bcmath
 доб-cтип
 внешн. Завиток
 доб-дом
 ext-fileinfo
 ext-gd
 ext-hash
 ext-iconv
 доб. Международный
 ext-json
 ext-libxml
 ext-mbstring
 ext-openssl
 доб-ПК
 ext-pdo_mysql
 ext-simplexml
 внешнее мыло
 розетки
 доб-натрий
 ext-xmlwriter
 доб-xsl
 ext-zip
 библиотека-libxml
 библиотека-openssl
 Adobe Commerce:
 ext-bcmath
 доб-cтип
 внешн. Завиток
 доб-дом
 ext-fileinfo
 ext-gd
 ext-hash
 ext-iconv
 доб. Международный
 ext-json
 ext-libxml
 ext-mbstring
 ext-openssl
 доб-ПК
 ext-pdo_mysql
 ext-simplexml
 внешнее мыло
 розетки
 доб-натрий
 ext-spl
 ext-xmlwriter
 доб-xsl
 ext-zip
 библиотека-libxml
 библиотека-openssl
 Для проверки установленных расширений:
 Список установленных модулей.
 Убедитесь, что установлены все необходимые расширения.
 Добавьте недостающие модули, используя тот же рабочий процесс, который использовался для установки PHP. Например, если вы используете  yum  для установки PHP, модули PHP 7.4 можно добавить с помощью:
  
 
 
 
 
 1
 
 yum -y install php74u-pdo php74u-mysqlnd php74u-opcache php74u-xml php74u-gd php74u-devel php74u-mysql php74u-intl php74u-mbstring php74u-bcmath-soap php74u-soap php74u-soap php74u-soap php74u-soap php74u-soap php74u
 
 
 Проверить настройки PHP 
 Если вы используете PHP 7.4.20, установите  pcre.jit = 0  в вашем файле  php.ini . Это позволит обойти ошибку PHP, препятствующую загрузке CSS.
 Установить системный часовой пояс для PHP; в противном случае ошибки, подобные следующему отображению во время установки, и связанные со временем операции, такие как cron, могут не работать:
  
 
 
 
 
 1
 
 PHP Предупреждение: date (): полагаться на настройки часового пояса системы небезопасно. [следующие сообщения]
 
 
 Установите предел памяти PHP.
 Наши подробные рекомендации:
 Компиляция кода или развертывание статических активов,  1G 
 Отладка,  2G 
 Тестирование,  ~ 3-4G 
 Увеличьте значения для PHP  realpath_cache_size  и  realpath_cache_ttl  до рекомендуемых настроек:
  
 
 
 
 
 1
2
 
 realpath_cache_size = 10M
realpath_cache_ttl = 7200
 
 
 Эти настройки позволяют процессам PHP кэшировать пути к файлам вместо того, чтобы искать их при каждой загрузке страницы.См. Раздел «Настройка производительности» в документации PHP.
 Включите  opcache.save_comments , который требуется для Magento 2.1 и новее.
 Мы рекомендуем вам включить PHP OPcache из соображений производительности. OPcache включен во многих дистрибутивах PHP.
 Magento 2.1 и более поздние версии используют комментарии кода PHP для генерации кода.
 Чтобы избежать проблем во время установки и обновления, мы настоятельно рекомендуем вам применить одни и те же настройки PHP как к конфигурации командной строки PHP, так и к конфигурации подключаемого модуля веб-сервера PHP.Для получения дополнительной информации см. Следующий раздел.
 Шаг 1. Найдите файлы конфигурации PHP 
 В этом разделе обсуждается, как найти файлы конфигурации, необходимые для обновления требуемых параметров.
 Найдите 
 файл конфигурации php.ini 
 Чтобы найти конфигурацию веб-сервера, запустите файл  phpinfo.php  в своем веб-браузере и найдите загруженный файл конфигурации   следующим образом:
 Чтобы найти конфигурацию командной строки PHP, введите
  
 
 
 
 
 1
 
 php --ini | grep "Загруженный файл конфигурации"
 
 
 Если у вас только один  php.ini , внесите в него изменения. Если у вас есть два файла  php.ini , внесите изменения в  во все файлы . Несоблюдение этого правила может привести к непредсказуемой работе.
 Найдите параметры конфигурации OPcache 
 Параметры PHP OPcache обычно находятся в  php.ini  или  opcache.ini . Расположение может зависеть от вашей операционной системы и версии PHP. Файл конфигурации OPcache может иметь раздел  opcache  или такие параметры, как  opcache.включить .
 Используйте следующие рекомендации, чтобы найти его:
 Веб-сервер Apache:
 Для Ubuntu с Apache настройки OPcache обычно находятся в  php.ini .
 Для CentOS с Apache или nginx настройки OPcache обычно находятся в  /etc/php.d/opcache.ini 
 Если нет, используйте следующую команду, чтобы найти его:
  
 
 
 
 
 1
 
 sudo find / -name 'opcache.ini '
 
 
 Веб-сервер
 nginx с PHP-FPM:  /etc/php/7.2/fpm/php.ini 
 Если у вас более одного  opcache.ini , измените их все.
 Шаг 2: Как установить параметры PHP 
 Для установки опций PHP:
 Откройте файл  php.ini  в текстовом редакторе.
 Найдите часовой пояс вашего сервера в доступных настройках часового пояса
 Найдите следующий параметр и при необходимости раскомментируйте его:
 Добавьте настройку часового пояса, которую вы нашли на шаге 2.
 Измените значение  memory_limit  на одно из значений, рекомендованных в начале этого раздела.
 Например,
 Добавьте или обновите конфигурацию  realpath_cache , чтобы она соответствовала следующим значениям:
  
 
 
 
 
 1
2
3
4
5
6
7
8
9
 
;
; Увеличить размер кеша realpath
;
realpath_cache_size = 10 МБ

;
; Увеличить кеш Realpath ttl
;
realpath_cache_ttl = 7200
 
 
 Сохраните изменения и выйдите из текстового редактора.
 Откройте другой  php.ini  (если они разные) и внесите в него те же изменения.
 Шаг 3. Установите параметры OPcache 
 Для установки опций  opcache.ini :
 Откройте файл конфигурации OPcache в текстовом редакторе:
  opcache.ini  (CentOS)
  php.ini  (Ubuntu)
  /etc/php/7.2/fpm/php.ini  (веб-сервер nginx (CentOS или Ubuntu))
 Найдите  opcache.save_comments  и при необходимости раскомментируйте.
 Убедитесь, что для него установлено значение  1 .
 Сохраните изменения и выйдите из текстового редактора.
 Перезагрузите веб-сервер:
 Apache, Ubuntu:  перезапуск службы apache2 
 Apache, CentOS:  перезапуск службы httpd 
 nginx, Ubuntu и CentOS:  перезапуск службы nginx 
 Поиск и устранение неисправностей 
 См.
Добавить комментарий Отменить ответ
Ваш адрес email не будет опубликован. Обязательные поля помечены *
Комментарий *
Имя * 
Email * 
Сайт