Download the PHP package dbeurive/trace without Composer

On this page you can find all versions of the php package dbeurive/trace. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package trace

introduction

It is a common practice to insert "traces" within the code, during the development process. This package takes care of the rendering of traces.

Traces are stored within a LOG container. Then they are dumped using a dumper. The dumper takes care of the rendering. One of the main functions of the dumper is to calculate the indentation from each trace.

Right now, there is only one dumper : this dumper generates a simple textual representation of the flow of traces. However, it is possible to create dumpers for any format (HTML, Markdown...). A dumper is just a class that implements a given interface.

Vocabulary

Trace

A trace is a message.

Batch

A batch (of traces) is a set of traces that must be written using the same indentation. Typically, all traces from a given function call are part of the same batch. All traces included within a batch are written by a single writer.

Let's consider the 4 following batches of traces ("A", "B", "C" and "D"):

--->root
    --->aaaaaaa
    aaaaaaaaaaa
        --->bbbbbbb
        bbbbbbbbbbb
        bbbbbbbbbbb
        --->ccccccc
        ccccccccccc
        ccccccccccc
    aaaaaaaaaaa
    --->ddddddd
    ddddddddddd
    ddddddddddd
root

We say that:

LOG container

A LOG container provides data storage for a given underlying storage.

Please note that, in theory, it is possible to implement LOG containers using any kind of data storage. However, due to the nature of the operations that need to be done, the data storage should provide database functionalities.

Synopsis

Consider the following example:

use dbeurive\Trace\LogContainer\Sqlite;
use dbeurive\Trace\Tracer;

// Create a LOG container. It is used to store data into the underlying storage.
$dbPath = __DIR__ . DIRECTORY_SEPARATOR . 'log.sqlite';
$logContainer = new Sqlite(array(Sqlite::CONF_KEY_DB_PATH => $dbPath, Sqlite::CONF_KEY_DB_OVERRIDE => true));

// Create a tracer that uses the LOG container to store the traces.
$TRACER = new Tracer($logContainer);

// Write traces from a function.
function fib($n) {
    global $TRACER;
    // Get a writer that will write traces for this function.
    $w = $TRACER->getWriter(__FUNCTION__ . "($n)");
    if ($n < 0) {
        $w->write('$n < 0 => return NULL');
        return NULL;
    } elseif ($n === 0) {
        $w->write('$n = 0 => return 0');
        return 0;
    } elseif ($n === 1 || $n === 2) {
        $w->write('$n = (1|2) => return 1');
        return 1;
    } else {
        $w->write("Calculate fib($n-1) + fib($n-2)");
        $r = fib($n-1) + fib($n-2);
        $w->write("fib($n-1) + fib($n-2) = $r");
        return $r;
    }
}

$x = 6;
// Get a write that will write traces for the main entry point.
$w = $TRACER->getWriter("Start the script", false);
$r = fib($x);
$w->write("fib($x)=$r");
$w->write("End of the script");

This code above will create a Sqlite database (the LOG container) that contains the traces. Let's say that the container's file name is log-container.sqlite.

Then dump the traces from the Sqlite database, using a dumper. For example, if you use the dumper that generates a simple textual representation of the flow of traces, you get:

Command:

php trace-dump.php sqlite:text-simple --tab "    " log-container.sqlite

Result:

Start the script
Call fib(6)
Calculate fib(6-1) + fib(6-2)
    Call fib(5)
    Calculate fib(5-1) + fib(5-2)
        Call fib(4)
        Calculate fib(4-1) + fib(4-2)
            Call fib(3)
            Calculate fib(3-1) + fib(3-2)
                Call fib(2)
                $n = (1|2) => return 1
                Call fib(1)
                $n = (1|2) => return 1
            fib(3-1) + fib(3-2) = 2
            Call fib(2)
            $n = (1|2) => return 1
        fib(4-1) + fib(4-2) = 3
        Call fib(3)
        Calculate fib(3-1) + fib(3-2)
            Call fib(2)
            $n = (1|2) => return 1
            Call fib(1)
            $n = (1|2) => return 1
        fib(3-1) + fib(3-2) = 2
    fib(5-1) + fib(5-2) = 5
    Call fib(4)
    Calculate fib(4-1) + fib(4-2)
        Call fib(3)
        Calculate fib(3-1) + fib(3-2)
            Call fib(2)
            $n = (1|2) => return 1
            Call fib(1)
            $n = (1|2) => return 1
        fib(3-1) + fib(3-2) = 2
        Call fib(2)
        $n = (1|2) => return 1
    fib(4-1) + fib(4-2) = 3
fib(6-1) + fib(6-2) = 8
fib(6)=8
End of the script

API

LOG container

Right now, there is only one LOG container available : the Sqlite LOG container. However, it is possible to create other LOG containers. A LOG container implements the interface \dbeurive\Trace\LogContainer\InterfaceLogContainer.

Sqlite LOG container

Constructor

The method below creates a new Sqlite LOG container.

public \dbeurive\Trace\LogContainer\Sqlite \dbeurive\Trace\LogContainer\Sqlite::__construct(array $inInitData)

The parameter $inInitData is an associative array that contains the following keys:

Example:

$dbPath = __DIR__ . DIRECTORY_SEPARATOR . 'log.sqlite';
$logContainer = new Sqlite(array(Sqlite::CONF_KEY_DB_PATH => $dbPath, Sqlite::CONF_KEY_DB_OVERRIDE => true));

Tracer

A tracer provides writers used to write traces. A tracer uses one (and only one) LOG container. In a mono thread application, only one tracer should be used. However, you can create as many tracers as you want. This may be helpful in order to organise things.

Constructor

The method below creates a new tracer.

public \dbeurive\trace\Tracer \dbeurive\trace\Tracer::__construct(InterfaceLogContainer $inLogContainer)

The parameter $inLogContainer contains the LOG container used to store the traces.

Get a new writer

The method below creates a new writer and returns it.

public \dbeurive\trace\Writer \dbeurive\trace\Tracer::getWriter($inOptMessage=null)

The parameter $inOptMessage represents an optional message that will be inserted into the LOG container.

The method returns a writer.

Writer

A writer writes traces to the LOG container. All traces written by a given writer have the same indentation level. Typically, we create a writer per function.

Write a trace into the LOG container

The method below writes a trace into the LOG container.

public \dbeurive\trace\Writer::write(string|array $inMessage, string $inOptType=InterfaceLogContainer::MESSAGE_TYPE_TEXT)

The parameter $inMessage represents the message to write.

The optional $inOptType parameter indicates the type of the message. The type can be:

Write the content of a variable

The method below writes the equivalent of a call to the function var_dump().

public dbeurive\trace\Writer::varDump($inVar, $inOptVarName=null)

The parameter $inVar represents the value of the variable to dump.

The optional parameter $inOptVarName represents the name of the variable.

Report the call to a function

The method can be used to signal the call to a given function.

public dbeurive\trace\Writer::call($inFunctionName)

The parameter $inFunctionName represents the name of a function.

Please note that this function is a shortcut to the call to: \dbeurive\trace\Writer::write("Call " . $inMessage)

Write a list of couples key -> value

The method below writes a list of couples "key -> value":

public dbeurive\trace\Writer::call(array $inList)

The parameter $inList is an associative array that contains the couples "key -> value" to write.

Analysis

The indentation level that applies to a given batch (of traces) depends on the one that applies to its parent. If the indentation level that applies to the parent is "N", then the one that applies to the children is "N+1".

Please note that this definition implies that the indentation level that applies to the root batch (which is never represented) is -1.

How to find the parent "P" of a given batch "B" ?

We consider the set "S" of batches that start before "B" (relatively to the flow of batches). All batches "X" within "S" have a first trace "First/X" that appears before "First/B" (relatively to the flow of traces). The parent of "B" ("P") is the (only) batch included in "S" which last line "Last/P" appears after "First/B" (relatively to the flow of traces).

Implementation

Log container

For these reasons, the best container for storing traces is a relational database.

Various relational databases may be used. However, for most cases, a Sqlite database should provide all the necessary functionalities, since this library should be used in development environment only.

Sqlite implementation

The text below describes the Sqlite implementation of the LOG container.

A tracer produces batches of traces. Batches are written by writers.

Note about multithreaded scripts:

You should create a tracer per thread. Each tracer should use its own LOG container.

CREATE TABLE tracer (
    id INTEGER PRIMARY KEY
);

A writer writes one batch of traces. The same indentation level applies to all traces from a batch of traces. Thus, the indentation level is a batch property.

CREATE TABLE writer (
    id           INTEGER PRIMARY KEY,
    fk_tracer_id INT NOT NULL,
    indent       INT DEFAULT 0,
    FOREIGN KEY(fk_tracer_id) REFERENCES tracer(id)
);

CREATE INDEX fk_tracer_id_index ON writer (fk_tracer_id);

Traces are written one after the other.

Identifying the parent of a given batch, identified by its id:

SELECT   trace2.fk_writer_id AS id,
         writer.indent AS indent,
         trace2.id AS traceId
FROM     trace AS trace1,
         trace AS trace2,
         trace AS trace3,
         writer
WHERE    trace1.fk_writer_id = :id
  AND    trace2.fk_writer_id = trace3.fk_writer_id
  AND    trace1.is_first = 1
  AND    trace2.is_first = 1
  AND    trace3.is_last = 1
  AND    trace2.id < trace1.id
  AND    trace3.id > trace1.id
  AND    writer.id = trace2.fk_writer_id
ORDER BY traceId DESC
LIMIT    1

If the previous request returns no record, then it means that the parent batch is the "root" batch.

General consideration

This code relies on the mechanism implemented within PHP 5 (and 7) to free resources.

http://php.net/manual/en/language.oop5.decon.php

PHP 5 introduces a destructor concept similar to that of other object-oriented languages, such as C++. The destructor method will be called as soon as there are no other references to a particular object, or in any order during the shutdown sequence.


All versions of trace with dependencies

PHP Build Version
Package Version
No informations.
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package dbeurive/trace contains the following files

Loading the files please wait ....