README

It's All About Readability

Introduction
Installation
Version Compatibility
Basic Usage
Detailed Usage
Loggers
Full Example
Issues
License
Testing
Contributing

Introduction

PHP dump logger uses Symfony's var-dumper to create a simple, easy to use, eye-friendly, and pretty log files for any PHP application. If you are a big fan of using dd() and dump(), this package is for you.

Example log file content:

Have you ever tried to log something with monolog, Symfony, or Laravel logger and tried to find the logged data inside a maze of text? Especially when you don't have time and don't want to go through installing and configuring Xdebug or there is a bug in production code, and you just want to see the API responses without messing with the code execution.

The problem with dd(), dump(), or var_dump() functions is that they print the data, which is something that sometimes you don't want, especially when the code execution should not be interrupted.

The first solution that comes to mind is to use a logger to log the data instead of using those print functions. But as I said, loggers aren't producing readable files, and sometimes you have to only provide them with a string, and they are incapable of directly logging a complex class. How nice would it be to have a functionality like dd() without interruption in the code?

Here php-dump-logger comes to the rescue.

php-dump-logger uses Symfony's var-dumper to generate the log content and then saves the output into a file. Which is by the way really pleasant in the eye. You can either log the data in a nice html or log format or even provide your own dumper.

Features

Readable log in html format
Readable log in log format
Ability to log classes, arrays, objects, and basically any variable you like. There is no limit.
Fully customization of log format and dumper
Separation of the daily and all in one logs
Logging file in a custom level
Changing the path and directory of the log

Installation

Install via composer:

 composer require salibhdr/php-dump-logger

Version Compatibility

PHP	PHP Dump Logger
7.0.x to 7.1.x	1.x
7.2.x to 8.2.x	2.x

Basic Usage

<?php

use SaliBhdr\DumpLog\Factory\Logger;

Logger::make()
        ->path('__path-to-dir__')
        ->log([
          "foo" => [
            "foo" => "bar"
            "tar" => "go"
            "zee" => "lorem"
          ]
          "tar" => [
            "foo" => "bar"
          ]
          "zee" => "lorem"
        ])

This will create a __path-to-dir__/dump/log.log file like this:

---| 2023-01-18 13:37:09 |-------------------------------------------------------------------------------------------

array:3 [
  "foo" => array:3 [
    "foo" => "bar"
    "tar" => "go"
    "zee" => "lorem"
  ]
  "tar" => array:1 [
    "foo" => "bar"
  ]
  "zee" => "lorem"
]

Methods

Each log level (info, error, warning, etc.) creates a separate log file with method's name.

use SaliBhdr\DumpLog\Factory\Logger;

$logger = Logger::make()
        ->path('__path-to-dir__');
        
$logger->emergency(mixed $data);
$logger->alert(mixed $data);
$logger->critical(mixed $data);
$logger->error(mixed $data);
$logger->warning(mixed $data);
$logger->notice(mixed $data);
$logger->info(mixed $data);
$logger->debug(mixed $data);
$logger->exception(\Throwable $e);
$logger->log(mixed $data);

Exception Logging

If you want to log the exception in a much more readable way You should use the exception() method. This method is good for creating logs for exceptions. If You want to see the trace of the exception you can set the second argument named $withTrace to true:

try {

    throw new \Exception('exception message', 500);
    
} catch (\Throwable $e) {

    $logger->exception($e, true);
}

Output exception.log:


---| 2023-01-18 14:01:54 |-------------------------------------------------------------------------------------------

array:5 [
  "class" => "Exception"
  "massage" => "exception message"
  "code" => 500
  "file" => "__path_to_file__"
  "line" => 356
  "trace" => array:12 [...] // appears only if $withTrace is true
]

Custom Log Level

As mentioned before each log level creates a separate log file. So you can create custom log level with custom file name by changing the value of $level argument in log() method:

   $logger->log($data, 'custom-level');

This will create a file named custom-level.log.

Path

By default, the path to log directory is set to be $_SERVER['DOCUMENT_ROOT'] but if you call this logger from a console command the document root will be null and the logger could not find a directory to save the file, and it will throw InvalidArgumentException. So make sure to provide the directory path like so:

$logger->path('__path-to-dir__');

Directory Name

By default, The parent directory of log files is called dump but you can change the directory name of the log file with dir() method:

$logger->dir('__dir-name__');

You can also use this dir() method to arrange your log files. for example if you want to add the custom logs in the separate directory you can do it like so:

$logger->dir('dump/custom')
       ->log($data, 'custom-level');

Directory Permission

Sometimes you want to put your log files in a directory with restricted permission. In order to do that you can change the log file's directory permission with the permission() method. remember that This directory permission is only applied in the directory's first creation. So you can't change the directory's permission after the creation. Remember to provide a group with the right permissions to create and execute the file in the directory. You don't want to create a directory that even PHP could not write into it. By default, the directory and the files inside it will have 0775 permission.

$logger->permission(0777);

Daily Log

Sometimes you want to log data daily into separate file's based on date, You can separate the log files daily with date suffix by calling the daily() method.

$logger->daily()
       ->info();

It will create file's like this for separate days:


info-2023-01-18.log
info-2023-01-19.log
info-2023-02-01.log

Silent Logging

Calling silent() method allows you to log data without throwing an error.

Remember, in some cases the logger will throw an error when the $path is empty, or when it couldn't write into the target file for permission reasons.

So if you want to avoid that, and you don't want to interrupt the code execution, you can call silent() method. In the background this method will force the logger to execute the code in try-catch block and return a boolean instead of the exception.

$logger->silent(); //result will be true for success and false for failed attempt to log

Loggers

Pretty Logger
Html Logger
Raw Logger
Custom Logger

Pretty Logger

The pretty logger is used for creating a log file with .log extension in a pretty readable way.

You can make the pretty logger class with logger factory class like so:

<?php

use SaliBhdr\DumpLog\Factory\Logger;

$logger = Logger::make(); // the pretty logger is the default logger

// or

$logger = Logger::make('pretty');

// or

$logger = Logger::pretty();

Html Logger

The html logger is used for creating a log file with .html extension in a pretty readable way. You can navigate throw different variables, toggle the multidimensional arrays and complex class properties.

You can make the html logger class with logger factory like so:

<?php

use SaliBhdr\DumpLog\Factory\Logger;

$logger = Logger::make('html');

// or

$logger = Logger::html();

Raw Logger

Raw Logger is base logger class that other loggers are using it. The only difference between Raw Logger and the others is that there is no dumper or path specified in this logger, and you have to provide a dumper and the file extension with dumper() and the path with path() method. Otherwise, it will throw SaliBhdr\DumpLog\Exceptions\InvalidArgumentException

Remember that the dumper should be the instance of Symfony\Component\VarDumper\Dumper\AbstractDumper. Feel free to create your own dumper and use the Raw logger.

example:

use SaliBhdr\DumpLog\Loggers\RawLogger;
use Symfony\Component\VarDumper\Dumper\CliDumper;

$dumper     = new CliDumper();
$logger     = new RawLogger();
$extension  = 'txt';

$logger->path('__path_to_dir__')
       ->dumper($dumper, $extension)
       ->log($data)

Custom Logger

You can create your own dump logger by implementing one of these interfaces:

SaliBhdr\DumpLog\Contracts\DumpLoggerInterface : Without the ability to change the dumper
SaliBhdr\DumpLog\Contracts\DumpLoggerAwareInterface : You have to add dumper() setter

You can also use the RawLogger in your own logger by first instantiating the RawLogger in your Logger and then use the SaliBhdr\DumpLog\Traits\LogsThroughRawLogger trait.

If you use DumpLoggerAwareInterface you should keep in mind that the dumper should implement SaliBhdr\DumpLog\Contracts\DumperStrategyInterface;

Example dumper strategy:

<?php

namespace App;

use SaliBhdr\DumpLog\Contracts\DumperStrategyInterface;
use Symfony\Component\VarDumper\Dumper\AbstractDumper;
use Symfony\Component\VarDumper\Dumper\CliDumper;

class CustomDumperStrategy implements DumperStrategyInterface
{

    public function getDumper() : AbstractDumper
    {
       # Here we want to render the log content with CliDumper
       return new CliDumper();
    }
    
    public function getExtension() : string
    {
       # Here we want to save it as text file
       return 'txt';
    }
    
    public function getTitle(): string
    {
        # title will be shown on top of each log (usually it's better to add the date and time)
        return "\n" . date('H:i:s') . "\n"
    }
    
}

And then you can use your own dumper strategy:

<?php

use App\CustomDumperStrategy;
use SaliBhdr\DumpLog\Contracts\DumpLoggerInterface;

class CustomTextLogger implements DumpLoggerInterface 
{
    use LogsThroughRawLogger;

    protected $logger;

    public function __construct()
    {        
        $this->logger = (new RawLogger())
            ->dumper(new CustomDumperStrategy())
            ->path('__path-to-dir__');
    }
}

Full Example

<?php

use SaliBhdr\DumpLog\Factory\Logger;

Logger::make()
        ->path('__path-to-dir__')
        ->dir('__custom-dir-name__')
        ->daily(true)
        ->silent(true)
        ->permission(0777)
        ->info($data);

Issues

You can report issues in GitHub repository here

License

PHP dump logger is released under the MIT License.

Created by Salar Bahador

salar bahador linkedin LinkedIn salar bahador github GitHub salar bahador packegist Packagist

Built with ❤ for you.

Testing

for testing:

composer test

for using php code sniffer:

composer csfix

for both csfix and test:

composer testfix

Contributing

Please see CONTRIBUTING for details.

salibhdr / php-dump-logger

Maintainers

Details