Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/theiconic/synopsis
PHP library to generate a language-agnostic description of PHP objects or values
https://github.com/theiconic/synopsis
debugging development introspection php php7 synopsis
Last synced: 3 months ago
JSON representation
PHP library to generate a language-agnostic description of PHP objects or values
- Host: GitHub
- URL: https://github.com/theiconic/synopsis
- Owner: theiconic
- License: mit
- Created: 2017-02-17T01:00:10.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2023-04-19T18:38:02.000Z (almost 2 years ago)
- Last Synced: 2024-10-20T14:44:05.068Z (3 months ago)
- Topics: debugging, development, introspection, php, php7, synopsis
- Language: PHP
- Homepage:
- Size: 99.6 KB
- Stars: 7
- Watchers: 78
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# synopsis
PHP library to generate a language-agnostic description of PHP objects or values
[](https://travis-ci.org/theiconic/synopsis)
[](https://coveralls.io/github/theiconic/synopsis?branch=master)
[](https://scrutinizer-ci.com/g/theiconic/synopsis/?branch=master)
[](https://packagist.org/packages/theiconic/synopsis)
[](https://packagist.org/packages/theiconic/synopsis)
[](https://packagist.org/packages/theiconic/synopsis)
## Purpose
This library can be used to generate language-agnostic descriptions of
PHP variables or objects that can then be sent over a transport to
another system, e.g. for debugging, monitoring and inspection purposes.
It generates a standardised representation that can easily be formatted
in different ways.
E.g. possible use-cases are
- sending data together with log messages to a logging service
- sending debug data to a debugging/inspection tool
- pretty-formatting exceptions including their traces and the arguments in the calls of those traces
- output data on different channels (e.g. terminal, web, etc.) via standardised formatters
## Setup (via Composer)
Simply import the library in composer
```$bash
composer require theiconic/synopsis
```
## Basic Usage
You will need to start off by instantiating the factory
```php
$factory = new TheIconic\Synopsis\Factory();
```
Now you can synopsise any value
```php
class MyClass
{
public $myProp = 1;
}
$myObject = new MyClass();
$myArray = [
'string' => 'Hello World!',
'integer' => 1,
'boolean' = true,
];
$objectSynopsis = $factory->synopsize($myObject);
$arraySynopsis = $factory->synopsize($myArray);
```
Each call to `synopsize()` generates an `AbstractSynopsis`
instance which describes the passed value.
Now use one of the formatters to format that data in a way
that you can send over a transport or use by other components.
```php
$formatter = new TheIconic\Synopsis\Formatter\ArrayFormatter();
$formatter->format($objectSynopsis);
/*
* [
* 'type' => 'MyClass',
* 'length' => 1,
* 'value' => ''
* 'children' => [
* 'myProp' => [
* 'type' => 'integer',
* 'length' => 1,
* 'value' => 1,
* ]
* ]
* ]
*/
$formatter->format($arraySynopsis);
/*
* [
* 'type' => 'array',
* 'length' => 3,
* 'value' => ''
* 'children' => [
* 'string' => [
* 'type' => 'string',
* 'length' => 12,
* 'value' => 'Hello World!',
* ]
* 'integer' => [
* 'type' => 'integer',
* 'length' => 1,
* 'value' => 1,
* ],
* 'string' => [
* 'type' => 'boolean',
* 'length' => 4,
* 'value' => 'true',
* ]
* ]
* ]
*/
```
## Object Synopsis
When synopsising objects, the factory checks if a custom
Synopsis class is registered for the type of the object (i.e. it's class name).
If so, then the special Synopsis type is used to synopsise the
object and the result entirely depends on its implementation.
Custom object types can be registered via
```php
$factory->addObjectType(MyClass::$class, MyClassSynopsis::class);
```
If no custom type is registered, default object synopsis is used.
A custom IteratorSynopsis type is registered for objects that implement
Iterator or IteratorAggregate interfaces.
### Default Object Synopsis
The default ObjectSynopsis implementation will inspect the object
for any public properties. Each of those properties will be
treated as the objects children and synopsised recursively.
The **length** will be the number of public properties found.
The objects class name will be used as the **type**.
To determine the **value**, the implementation will check for the
presence and accessibility of any of the following methods in this order
- __toSynopsisValue
- __toString
- getId
- getName
The first method found will be executed and it's return value will
be cast to string and used as the objects **value**.
### Default Iterator Synopsis
The default IteratorSynopsis implementation will iterate through
the object, synopsise any of the iteration values and add them as
children.
## Resource Synopsis
When synopsising PHP resource pointers, the factory checks if a custom
Synopsis class is registered for the type of resource (determined via `get_resource_type()`).
If so, that type will be used.
By default, custom resource types are registered for some filetypes
and streams and they will use `stream_get_meta_data()` to determine
the resource uri and use it as the **value**.
Custom resource types can be registered via
```php
$factory->addResourceType(MyClass::$class, MyClassSynopsis::class);
```
## Exception Synopsis
Exceptions and their traces are synopsised in a special way
adding additional properties to the synopsis objects.
These can be utilised in special Exception formatters.
### ExceptionSynopsis
- **type**: the exception type
- **value**: the exception message
- **length**: the length of the stack trace
- **line**: the line
- **file**: the file
- **children**: the synopsised stack trace
### TraceSynopsis
- **type**: a string representation of the full call
- **value**: a string representation of the file and line
- **length**: the number of call parameters
- **line**: the line
- **file**: the file
- **class**: the class name
- **function**: the function/method name
- **children**: the synopsised call parameters (if any)
## Overriding default Synopsis implementations
To override the behaviour for any of the types, simply implement
your own Synopsis class (inheriting from `AbstractSynopsis`) and
register it with the factory via e.g.
```php
$factory->addType('string', MyStringSynopsis::class);
```
## License
THE ICONIC Synopsis library for PHP is released under the MIT License.