Merge pull request #24 from avto-dev/add-dev-functions

Add helpers functions and `VarDumper` service

Author: tarampampam

CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog][keepachangelog] and this project adheres to [Semantic Versioning][semver].
 
+## v1.9.0
+
+### Added
+
+- Service `Laravel\VarDumper` (with middleware and stack instance)
+- Global helpers file (namespace `\dev\...`)
+- Function `\dev\dump(...$arguments)`
+- Function `\dev\dd(...$arguments)`
+
 ## v1.8.0
 
 ### Added

Makefile

@@ -0,0 +1,34 @@
+#!/usr/bin/make
+# Makefile readme (ru): <http://linux.yaroslavl.ru/docs/prog/gnu_make_3-79_russian_manual.html>
+# Makefile readme (en): <https://www.gnu.org/software/make/manual/html_node/index.html#SEC_Contents>
+
+docker_bin := $(shell command -v docker 2> /dev/null)
+
+SHELL = /bin/sh
+PHP_IMAGE = composer:1.8
+RUN_ARGS = --rm -v "$(shell pwd):/src:cached" -v "/etc/passwd:/etc/passwd:ro" -v "/etc/group:/etc/group:ro" \
+           --workdir "/src" -u "$(shell id -u):$(shell id -g)"
+RUN_INTERACTIVE ?= --tty --interactive
+
+.PHONY : help install test shell
+.SILENT : help install shell test
+.DEFAULT_GOAL : help
+
+# This will output the help for each task. thanks to https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
+help: ## Show this help
+	@printf "\033[33m%s:\033[0m\n" 'Available commands'
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  \033[32m%-14s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Install all php dependencies
+	$(docker_bin) run $(RUN_ARGS) $(RUN_INTERACTIVE) "$(PHP_IMAGE)" composer install --no-interaction --ansi --no-suggest --prefer-dist
+
+test: ## Execute php tests and linters
+	$(docker_bin) run $(RUN_ARGS) $(RUN_INTERACTIVE) "$(PHP_IMAGE)" composer test
+
+shell: ## Start shell into container with php
+	$(docker_bin) run $(RUN_ARGS) $(RUN_INTERACTIVE) \
+	  -e "PS1=\[\033[1;32m\]🐳 \[\033[1;36m\][\u@\h] \[\033[1;34m\]\w\[\033[0;35m\] \[\033[1;36m\]# \[\033[0m\]" \
+	  "$(PHP_IMAGE)" bash
+
+clean: ## Remove all dependencies and unimportant files
+	-rm -Rf ./composer.lock ./vendor

README.md

@@ -28,13 +28,23 @@ $ composer require --dev avto-dev/dev-tools "^1.7.1"
 
 Данный пакет позволяет легко интегрировать в ваше приложение вспомогательные инструменты, позволяющие более эффективно вести разработку. Разделить их можно на следующие группы:
 
+## Вспомогательные функции
+
+Имя функции | Её назначение
+----------- | -------------
+`\dev\dd(...$arguments)` | Выводит удобочитаемый дамп переданных в функцию значений, бросив специальным образом оформленное исключение (при вызове в HTTP-контексте; в CLI контексте работает как обычная `\dd(...)`) <sup>*</sup>
+`\dev\dump(...$arguments)` | Выводит удобочитаемый дамп переданных в функцию значений не прерывая обработку запроса. Необходима регистрация сервис-провайдера [VarDumper](./src/Laravel/VarDumper/ServiceProvider.php) (при вызове в HTTP-контексте; в CLI контексте работает как обычная `\dump(...)`) <sup>*</sup>
+
+> **<sup> * </sup>** корректно работает в связке Laravel + [RoadRunner][roadrunner] (возможно и ReactPHP - не проверено)
+
 ## Вспомогательные сервисы для Laravel
 
 Для Laravel-приложений вы можете подключать следующие сервис-провайдеры:
 
 Сервис-провайдер | Его назначение
 ---------------- | --------------
 [DatabaseQueriesLogger](./src/Laravel/DatabaseQueriesLogger/ServiceProvider.php) | Производит запись всех обращений к базе данных в лог-файл приложения
+[VarDumper](./src/Laravel/VarDumper/ServiceProvider.php) | Модифицирует HTTP-ответ приложения, добавляя в него результат работы вызовов функции `\dev\dump()`. Данный сервис-провайдер регистрируется **автоматически**
 
 ## Unit-тестирование приложения
 
@@ -180,3 +190,4 @@ This is open-sourced software licensed under the [MIT License][link_license].
 [link_pulls]:https://github.com/avto-dev/dev-tools/pulls
 [link_license]:https://github.com/avto-dev/dev-tools/blob/master/LICENSE
 [getcomposer]:https://getcomposer.org/download/
+[roadrunner]:https://github.com/spiral/roadrunner

composer.json

@@ -15,30 +15,42 @@
     ],
     "require": {
         "php": ">=7.0",
-        "phpunit/phpunit": "^6.5 || ~7.0 <7.5.0"
+        "phpunit/phpunit": "^6.5 || ~7.0 <7.5.0",
+        "symfony/var-dumper": "~3.3 || ^4.0"
     },
     "require-dev": {
         "ext-pdo_sqlite": "*",
         "ext-sqlite3": "*",
         "jeremeamia/superclosure": "^2.4",
         "nikic/php-parser": "^2.0 || ^3.0 || ^4.0",
         "laravel/laravel": ">=5.5 <5.8.0",
-        "mockery/mockery": "~1.0",
-        "symfony/var-dumper": "~3.3 || ^4.0"
+        "phpstan/phpstan": "~0.9 || ^0.10",
+        "mockery/mockery": "~1.0"
     },
     "autoload": {
         "psr-4": {
             "AvtoDev\\DevTools\\": "src"
-        }
+        },
+        "files": [
+            "src/functions/dump.php"
+        ]
     },
     "autoload-dev": {
         "psr-4": {
             "Tests\\AvtoDev\\DevTools\\": "tests"
         }
     },
+    "extra": {
+        "laravel": {
+            "providers": [
+                "AvtoDev\\DevTools\\Laravel\\VarDumper\\ServiceProvider"
+            ]
+        }
+    },
     "scripts": {
-        "test": "@php ./vendor/bin/phpunit --no-coverage",
-        "test-cover": "@php ./vendor/bin/phpunit"
+        "test": "@php ./vendor/bin/phpunit --no-coverage --testdox --colors=always",
+        "test-cover": "@php ./vendor/bin/phpunit",
+        "phpstan": "@php ./vendor/bin/phpstan analyze --no-progress --ansi --level=max ./src"
     },
     "suggest": {
         "jeremeamia/superclosure": "Library for closures serialization and hashing",

src/Exceptions/VarDumperException.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace AvtoDev\DevTools\Exceptions;
+
+use Throwable;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class VarDumperException extends \Exception
+{
+    /**
+     * VarDumperException constructor.
+     *
+     * @param string         $message
+     * @param int            $code
+     * @param Throwable|null $previous
+     */
+    public function __construct(string $message,
+                                int $code = Response::HTTP_INTERNAL_SERVER_ERROR,
+                                Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+    }
+
+    /**
+     * Report the exception.
+     *
+     * Since "illuminate/framework" v5.5.
+     *
+     * @link https://laravel.com/docs/5.5/errors#renderable-exceptions
+     *
+     * @return void
+     */
+    public function report()
+    {
+        // Do nothing
+    }
+
+    /**
+     * Render the exception into an HTTP response.
+     *
+     * Since "illuminate/framework" v5.5.
+     *
+     * @link https://laravel.com/docs/5.5/errors#renderable-exceptions
+     *
+     * @param Request|null $request
+     *
+     * @return Response
+     */
+    public function render(Request $request = null): Response
+    {
+        return new Response(static::generateView($this->getMessage()), $this->getCode());
+    }
+
+    /**
+     * Generate HTML representation of some content.
+     *
+     * @param string $content
+     *
+     * @return string
+     */
+    protected static function generateView($content):string
+    {
+        return <<<EOT
+<html>
+    <head></head>
+    <body>
+        $content
+    </body>
+</html>
+EOT;
+    }
+}

src/Laravel/VarDumper/DumpStack.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace AvtoDev\DevTools\Laravel\VarDumper;
+
+class DumpStack implements DumpStackInterface
+{
+    /**
+     * @var string[]
+     */
+    protected $stack = [];
+
+    /**
+     * {@inheritdoc}
+     */
+    public function push(string $data)
+    {
+        $this->stack[] = $data;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function clear()
+    {
+        $this->stack = [];
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function all(): array
+    {
+        return $this->stack;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function count(): int
+    {
+        return \count($this->stack);
+    }
+}

src/Laravel/VarDumper/DumpStackInterface.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace AvtoDev\DevTools\Laravel\VarDumper;
+
+use Countable;
+
+interface DumpStackInterface extends Countable
+{
+    /**
+     * Push an element into stack.
+     *
+     * @param string $data
+     */
+    public function push(string $data);
+
+    /**
+     * Clear stack.
+     *
+     * @return void
+     */
+    public function clear();
+
+    /**
+     * Get all stack elements.
+     *
+     * @return string[]
+     */
+    public function all(): array;
+}

src/Laravel/VarDumper/ServiceProvider.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace AvtoDev\DevTools\Laravel\VarDumper;
+
+use Illuminate\Contracts\Http\Kernel;
+use Illuminate\Support\ServiceProvider as IlluminateServiceProvider;
+
+class ServiceProvider extends IlluminateServiceProvider
+{
+    /**
+     * Register service and listener.
+     *
+     * @return void
+     */
+    public function boot()
+    {
+        $this->app->make(Kernel::class)->pushMiddleware(VarDumperMiddleware::class);
+    }
+
+    /**
+     * Register services.
+     *
+     * @return void
+     */
+    public function register()
+    {
+        $this->app->singleton(DumpStackInterface::class, DumpStack::class);
+    }
+}

src/Laravel/VarDumper/VarDumperMiddleware.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types = 1);
+
+namespace AvtoDev\DevTools\Laravel\VarDumper;
+
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+
+/**
+ * @link https://laravel.com/docs/5.5/middleware#defining-middleware Before & After Middleware
+ */
+class VarDumperMiddleware
+{
+    /**
+     * @var DumpStackInterface
+     */
+    protected $stack;
+
+    /**
+     * Middleware constructor.
+     *
+     * @param DumpStackInterface $stack
+     */
+    public function __construct(DumpStackInterface $stack)
+    {
+        $this->stack = $stack;
+    }
+
+    /**
+     * Modify response after the request is handled by the application.
+     *
+     * @param Request $request
+     * @param Closure $next
+     *
+     * @return mixed
+     */
+    public function handle(Request $request, Closure $next)
+    {
+        /** @var Response $response */
+        $response = $next($request);
+
+        if ($this->stack->count() > 0) {
+            $dumped = \implode(\PHP_EOL, $this->stack->all());
+
+            $this->stack->clear();
+
+            $response->setContent($dumped . $response->getContent());
+        }
+
+        return $response;
+    }
+}