diff --git a/.github/workflows/psalm.yml b/.github/workflows/psalm.yml
new file mode 100644
index 00000000..d2b754ee
--- /dev/null
+++ b/.github/workflows/psalm.yml
@@ -0,0 +1,65 @@
+name: Psalm
+
+on:
+ pull_request:
+ paths-ignore:
+ - 'docs/**'
+ - 'bin/**'
+ - 'resources/**'
+ - 'README.md'
+ - 'CHANGELOG.md'
+ - '.gitignore'
+ - '.gitattributes'
+ - '.editorconfig'
+ - 'psalm.xml'
+
+ push:
+ paths-ignore:
+ - 'docs/**'
+ - 'bin/**'
+ - 'resources/**'
+ - 'README.md'
+ - 'CHANGELOG.md'
+ - '.gitignore'
+ - '.gitattributes'
+ - '.editorconfig'
+ - 'psalm.xml'
+
+jobs:
+ psalm:
+ name: Psalm Validation (PHP ${{ matrix.php }}, OS ${{ matrix.os }})
+ runs-on: ${{ matrix.os }}
+ continue-on-error: true
+ strategy:
+ fail-fast: false
+ matrix:
+ php: [8.2]
+ os: [ubuntu-latest]
+ steps:
+ - name: Set up PHP ${{ matrix.php }}
+ uses: shivammathur/setup-php@v2
+ with:
+ php-version: ${{ matrix.php }}
+ extensions: dom
+
+ - name: Check Out Code
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 1
+
+ - name: Get Composer Cache Directory
+ id: composer-cache
+ run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+ - name: Cache Dependencies
+ uses: actions/cache@v3
+ with:
+ path: ${{ steps.composer-cache.outputs.dir }}
+ key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+ restore-keys: php-${{ matrix.php }}-${{ runner.os }}-composer-
+
+ - name: Install Composer Dependencies
+ run: composer install --prefer-dist --no-interaction
+
+ - name: Run Tests
+ run: vendor/bin/psalm
diff --git a/.github/workflows/run-test-suite.yml b/.github/workflows/run-test-suite.yml
new file mode 100644
index 00000000..3ee86004
--- /dev/null
+++ b/.github/workflows/run-test-suite.yml
@@ -0,0 +1,112 @@
+name: Unit
+
+on:
+ workflow_call:
+ inputs:
+ test-suite:
+ required: true
+ type: string
+ fail-fast:
+ required: false
+ type: boolean
+ default: true
+ test-timeout:
+ required: false
+ type: number
+ default: 15
+
+ pull_request:
+ paths-ignore:
+ - 'docs/**'
+ - 'bin/**'
+ - 'resources/**'
+ - 'README.md'
+ - 'CHANGELOG.md'
+ - '.gitignore'
+ - '.gitattributes'
+ - '.editorconfig'
+ - 'psalm.xml'
+
+ push:
+ paths-ignore:
+ - 'docs/**'
+ - 'bin/**'
+ - 'resources/**'
+ - 'README.md'
+ - 'CHANGELOG.md'
+ - '.gitignore'
+ - '.gitattributes'
+ - '.editorconfig'
+ - 'psalm.xml'
+
+jobs:
+ test:
+ name: (PHP ${{ matrix.php }}, ${{ matrix.os }}, ${{ matrix.dependencies }} deps
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: ${{ matrix.timeout-minutes }}
+ env: { GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}' }
+ strategy:
+ fail-fast: ${{ inputs.fail-fast }}
+ matrix:
+ php: [ 8.1, 8.2 ]
+ os: [ ubuntu-latest, windows-latest ]
+ dependencies: [ lowest , highest ]
+ timeout-minutes: [ '${{ inputs.test-timeout }}' ]
+ exclude:
+ - os: windows-latest
+ php: 8.2
+ include:
+ - os: ubuntu-latest
+ php: 8.3
+ dependencies: highest
+ timeout-minutes: 40
+ steps:
+ - name: Set Git To Use LF
+ run: |
+ git config --global core.autocrlf false
+ git config --global core.eol lf
+
+ - name: Setup PHP ${{ matrix.php }}
+ uses: shivammathur/setup-php@v2
+ with:
+ php-version: ${{ matrix.php }}
+ tools: composer:v2
+ extensions: sockets, curl
+
+ - name: Check Out Code
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 1
+
+ - name: Validate composer.json and composer.lock
+ run: composer validate --strict
+
+ - name: Get Composer Cache Directory
+ id: composer-cache
+ run: |
+ echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+ - name: Cache Composer Dependencies
+ uses: actions/cache@v3
+ with:
+ path: ${{ steps.composer-cache.outputs.dir }}
+ key: php-${{ matrix.php }}-${{ matrix.os }}-composer-${{ hashFiles('**/composer.lock') }}
+ restore-keys: |
+ php-${{ matrix.php }}-${{ matrix.os }}-composer-
+
+ - name: Install lowest dependencies from composer.json
+ if: matrix.dependencies == 'lowest'
+ run: composer update --no-interaction --no-progress --prefer-lowest
+
+ - name: Validate lowest dependencies
+ if: matrix.dependencies == 'lowest'
+ env:
+ COMPOSER_POOL_OPTIMIZER: 0
+ run: vendor/bin/validate-prefer-lowest
+
+ - name: Install highest dependencies from composer.json
+ if: matrix.dependencies == 'highest'
+ run: composer update --no-interaction --no-progress
+
+ - name: Run tests
+ run: vendor/bin/phpunit --testsuite=${{ inputs.test-suite }} --testdox
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
new file mode 100644
index 00000000..3adb5889
--- /dev/null
+++ b/.github/workflows/security.yml
@@ -0,0 +1,65 @@
+name: Security
+
+on:
+ pull_request:
+ paths-ignore:
+ - 'docs/**'
+ - 'bin/**'
+ - 'resources/**'
+ - 'README.md'
+ - 'CHANGELOG.md'
+ - '.gitignore'
+ - '.gitattributes'
+ - '.editorconfig'
+ - 'psalm.xml'
+
+ push:
+ paths-ignore:
+ - 'docs/**'
+ - 'bin/**'
+ - 'resources/**'
+ - 'README.md'
+ - 'CHANGELOG.md'
+ - '.gitignore'
+ - '.gitattributes'
+ - '.editorconfig'
+ - 'psalm.xml'
+
+jobs:
+ security:
+ name: Security Checks (PHP ${{ matrix.php }}, OS ${{ matrix.os }})
+ runs-on: ${{ matrix.os }}
+ strategy:
+ fail-fast: false
+ matrix:
+ # Note: This workflow requires only the LATEST version of PHP
+ php: [ 8.2 ]
+ os: [ ubuntu-latest ]
+ steps:
+ - name: Set up PHP ${{ matrix.php }}
+ uses: shivammathur/setup-php@v2
+ with:
+ php-version: ${{ matrix.php }}
+ extensions: dom, sockets, grpc, curl
+
+ - name: Check Out Code
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 1
+
+ - name: Get Composer Cache Directory
+ id: composer-cache
+ run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+ - name: Cache Dependencies
+ uses: actions/cache@v3
+ with:
+ path: ${{ steps.composer-cache.outputs.dir }}
+ key: php-${{ matrix.php }}-${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+ restore-keys: php-${{ matrix.php }}-${{ runner.os }}-composer-
+
+ - name: Install Composer Dependencies
+ run: composer install --prefer-dist --no-interaction
+
+ - name: Verify
+ run: composer require --dev roave/security-advisories:dev-latest
diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml
new file mode 100644
index 00000000..d8e8773b
--- /dev/null
+++ b/.github/workflows/testing.yml
@@ -0,0 +1,11 @@
+name: Testing
+
+on: [push, pull_request]
+
+jobs:
+ unit:
+ name: Unit Testing
+ uses: ./.github/workflows/run-test-suite.yml
+ with:
+ fail-fast: false
+ test-suite: Unit
diff --git a/README.md b/README.md
index e454efbe..48aba03a 100644
--- a/README.md
+++ b/README.md
@@ -12,26 +12,55 @@
[![Twitter](https://img.shields.io/badge/-Follow-black?style=flat-square&logo=X)](https://twitter.com/buggregator)
[![Discord](https://img.shields.io/discord/1172942458598985738?style=flat-square&logo=discord&color=0000ff)](https://discord.gg/qF3HpXhMEP)
-
-
-- [Intro](#intro)
+
+
+**Buggregator Trap** is a minified version of the [Buggregator Server](https://github.com/buggregator/server)
+in the form of a terminal application and a set of utilities to assist with debugging.
+The package is designed to enhance the debugging experience in conjunction with the Buggregator Server.
+
- [Installation](#installation)
+- [Overview](#overview)
- [Usage](#usage)
- [Contributing](#contributing)
- [License](#license)
+## Installation
+
+To install Buggregator Trap in your PHP application, add the package as a dev dependency
+to your project using Composer:
+
+```bash
+composer require --dev buggregator/trap
+```
+
+[![PHP](https://img.shields.io/packagist/php-v/buggregator/trap.svg?style=flat-square&logo=php)](https://packagist.org/packages/buggregator/trap)
+[![Latest Version on Packagist](https://img.shields.io/packagist/v/buggregator/trap.svg?style=flat-square&logo=packagist)](https://packagist.org/packages/buggregator/trap)
+[![License](https://img.shields.io/packagist/l/buggregator/trap.svg?style=flat-square)](LICENSE.md)
+[![Total Downloads](https://img.shields.io/packagist/dt/buggregator/trap.svg?style=flat-square)](https://packagist.org/packages/buggregator/trap)
+
+And that's it. Trap is [ready to go](#usage).
+
+## Overview
-## Intro
+Buggregator Trap provides a toolkit for use in your code. Firstly, just having Buggregator Trap in your
+package enhances the capabilities of Symfony Var-Dumper.
-Buggregator Trap, the streamlined Command Line Interface (CLI) version of Buggregator, marks a new era in debugging PHP
-applications. Boasting an array of powerful debugging "traps", including:
+If you've already worked with google/protobuf, you probably know how unpleasant it can be.
+Now let's compare the dumps of protobuf-message: on the left (with trap) and on the right (without trap).
+
+![trap-proto-diff](https://github.com/buggregator/trap/assets/4152481/30662429-809e-422a-83c6-61d7d2788b18)
+
+This simultaneously compact and informative output format of protobuf message will be just as compact
+and informative in the Buggregator Server interface. Now, working with protobuf is enjoyable.
+
+---
+
+Buggreagtor Trap includes a console application - a mini-server.
+The application is entirely written in PHP and does not require Docker to be installed in the system.
+It may seem like it's just the same as the `symfony/var-dumper` server, but it's not.
+Buggregator Trap boasts a much wider range of handlers ("traps") for debug messages:
- Symfony var-dumper,
- Monolog,
@@ -39,18 +68,11 @@ applications. Boasting an array of powerful debugging "traps", including:
- SMTP,
- HTTP dumps,
- Ray,
-- And any raw data
-
-This lightweight tool facilitates and streamlines the process of debugging for developers, regardless of their
-environment.
+- Any raw data
-It enables you to easily install a client in your PHP application using a Composer package and run a local server
-specifically designed for debugging. This isn't just a debugging tool, it's a supercharged version of
-the `symfony/var-dumper` server, designed to offer more versatility and in-depth insights into your code.
+You can effortlessly visualize and analyze console information about various elements of your codebase.
-Now you can effortlessly visualize and analyze console information about various elements of your codebase.
-
-Here's a sneak peek into the console output you can expect with traps:
+Here's a sneak peek into the console output you can expect with Trap:
| symfony/var-dumper (proto) | Binary Data |
|--------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
@@ -60,40 +82,39 @@ Here's a sneak peek into the console output you can expect with traps:
|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| ![smtp](https://github.com/buggregator/trap/assets/4152481/b11c4a7f-072a-4e66-b11d-9bbd3177bfe2) | ![http-dump](https://github.com/buggregator/trap/assets/4152481/48201ce6-7756-4402-8954-76a27489b632) |
-In addition to the local debugging features, Buggregator Trap provides an innovative functionality as a proxy client. It
-can transmit data to a remote Buggregator server, thereby facilitating a centralized debugging process for your team or
-organization.
-
-## Installation
+---
-To install Buggregator Trap in your PHP application, add the package as a dependency to your project using Composer:
+Additionally, you can manually set traps in the code. Use the `trap()` function,
+which works almost the same as Symfony's `dump()`, but configures the dumper to send dumps to the local server,
+unless other user settings are provided.
-```bash
-composer require --dev buggregator/trap
-```
+---
+We care about the quality of our products' codebase and strive to provide the best user experience.
+Buggregator Trap has passed the Proof of Concept stage and is now an important part of the Buggregator ecosystem.
+We have big plans for the development of the entire ecosystem and we would be delighted if you join us on this journey.
## Usage
-After successfully installing Buggregator Trap, you can initiate the debugging process by using the following command:
+After successfully [installing](#installation) Buggregator Trap, you can initiate the debugging process by using the following command:
```bash
vendor/bin/trap
```
-This command will activate the Trap server, setting it up to listen for all TCP requests. Upon receiving these requests,
-the server will search for a corresponding listener that can process the incoming data and display a dump accordingly.
+This command will start the Trap server, ready to receive any debug messages. Once a debug message is trapped, you will see a convenient report about it right here in the terminal.
Then just call the `trap()` function in your code:
```php
-trap(); // dump current stack trace
-trap($var); // dump variable
-trap($var, foo: $far, bar: $bar); // dump variables sequence
+trap(); // dump the current stack trace
+trap($var); // dump a variable
+trap($var, foo: $far, bar: $bar); // dump a variables sequence
```
-The `trap()` function configures `$_SERVER['REMOTE_ADDR']` and `$_SERVER['REMOTE_PORT']` automatically, if they are not
-set. Also, it can dump google/protobuf messages.
+> **Note**:
+> The `trap()` function configures `$_SERVER['REMOTE_ADDR']` and `$_SERVER['REMOTE_PORT']` automatically,
+> if they are not set.
### Default port
@@ -159,3 +180,22 @@ becoming a better developer. So, don't hesitate to jump in and start contributin
## License
Buggregator Trap is open-sourced software licensed under the BSD-3 license.
+
+
+
+
+
diff --git a/composer.json b/composer.json
index c69e97f8..1c999455 100644
--- a/composer.json
+++ b/composer.json
@@ -2,7 +2,11 @@
"name": "buggregator/trap",
"type": "library",
"license": "BSD-3-Clause",
+ "description": "A simple and powerful tool for debugging PHP applications.",
"homepage": "https://buggregator.dev/",
+ "keywords": [
+ "debug", "cli", "console", "sentry", "smtp", "dump"
+ ],
"authors": [
{
"name": "Aleksei Gagarin (roxblnfk)",
@@ -55,16 +59,17 @@
"nunomaduro/termwind": "^1.15",
"nyholm/psr7": "^1.8",
"php-http/message": "^1.15",
- "psr/http-message": "^1 || ^2",
- "symfony/console": "^5 || ^6 || ^7"
+ "psr/http-message": "^1.1 || ^2",
+ "symfony/console": "^5.4 || ^6 || ^7"
},
"suggest": {
"symfony/var-dumper": "To use the trap() function"
},
"require-dev": {
+ "dereuromark/composer-prefer-lowest": "^0.1.10",
"google/protobuf": "^3.23",
"phpunit/phpunit": "^10.4",
- "vimeo/psalm": "^5.11",
- "symfony/var-dumper": "^6 || ^7"
+ "symfony/var-dumper": "^6 || ^7",
+ "vimeo/psalm": "^5.11"
}
}
diff --git a/phpunit.xml b/phpunit.xml
index d92f77f0..c2d8d4a1 100644
--- a/phpunit.xml
+++ b/phpunit.xml
@@ -1,17 +1,19 @@
-
- tests
+
+ tests/Unit