Merge pull request #10 from crowdsecurity/feature/packaging

Update doc and prepare composer.json to be published to packagist

Author: mobula9

.github/workflows/tests.yml

@@ -1,4 +1,4 @@
-name: Tests
+name: tests
 
 on:
     push:

README.md

@@ -1,45 +1,76 @@
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/crowdsecurity/crowdsec/master/docs/assets/images/crowdsec_logo.png" alt="CrowdSec" title="CrowdSec" width="200" height="120"/>
+</p>
+
 # PHP Bouncer Library
 
-The official PHP client for the CrowdSec APIs (LAPI or CAPI).
+> The official PHP bouncer library for the CrowdSec LAPI/CAPI
+
+<p align="center">
+<img src="https://img.shields.io/github/workflow/status/crowdsecurity/php-cs-bouncer/tests/main">
+<img src="https://img.shields.io/github/license/crowdsecurity/php-cs-bouncer">
+<img src="https://img.shields.io/github/v/release/crowdsecurity/php-cs-bouncer?include_prereleases">
+</p>
+
+<p align="center">
+:books: <a href="https://doc.crowdsec.net">Documentation</a>
+:diamond_shape_with_a_dot_inside: <a href="https://hub.crowdsec.net">Hub</a>
+:speech_balloon: <a href="https://discourse.crowdsec.net">Discourse Forum</a>
+:speech_balloon: <a href="https://gitter.im/crowdsec-project/community?utm_source=share-link&utm_medium=link&utm_campaign=share-link">Gitter Chat</a>
+</p>
+
+> This library allows you to create CrowdSec bouncers for PHP applications or frameworks like e-commerce, blog or other exposed applications.
 
-This client helps to create CrowdSec bouncers for PHP applications or frameworks (e-commerce, blog, other apps...).
+## Features
 
+- ✅ Fast API client
+- ✅ LAPI Support (CAPI not supported yet)
+- ✅ Built-in support for the most known cache systems like Redis, Memcached, PhpFiles
+- ✅ **Live mode** or **Stream mode**
+- ✅ Events logged using monolog
+- ✅ Large PHP matrix compatibility: 7.2.x, 7.3.x, 7.4.x and 8.0.x
+- ✅ Cap remediation level (ex: for sensitives websites: ban will be capped to captcha)
+- ✅ Clear and prune the cache
 ## Getting started
 
-View `docs/getting-started.md` to learn how to include this library in your project.
+### Installing CrowdSec Bouncer library
+
+The recommended way to install CrowdSec Bouncer library is through [Composer](https://getcomposer.org/).
+
+```bash
+composer require crowdsec/bouncer
+```
+
+```php
+
+/* To get a token: "cscli bouncers add <name-of-your-php-bouncer> */
+$apiToken = 'YOUR_TOKEN';
+
+/* Select the best cache adapter for your needs (Memcached, Redis, PhpFiles, ...) */
+$cacheAdapter = new Symfony\Component\Cache\Adapter\PhpFilesAdapter();
 
-You will find the full documenation here: (...) TODO P2
+$bouncer = new CrowdSecBouncer\Bouncer();
+$bouncer->configure(['api_token'=> $apiToken], $cacheAdapter);
 
-# Sources
+$remediation = $bouncer->getRemediationForIp($blockedIp);// Return "ban", "captcha" or "bypass"
+```
 
-- https://thephp.website/en/issue/php-docker-quick-setup/
+View [`docs/getting-started.md`](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/docs/getting-started.rst) to learn how to include this library in your project in minutes.
 
-# Licence
+## Future
+- Retrieve cache items with pagination
+- Release 1.0.0 version
+- Direct CAPI support
+- Support more cache systems (Apcu, Couchbase, Doctrine, Pdo)
+- Publish load tests (compare performances)
+- Report Code coverage
+- Setup Xdebug environment with Docker
 
-MIT License. Details in the `./LICENSE` file.
+## Licence
 
-# TODO
+[MIT License](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/LICENSE)
 
-Features:
-- [x] Fast API client
-- [x] LAPI Support
-- [x] Built-in support for the most known cache systems: Redis, Memcached, PhpFiles
-- [x] Live mode
-- [x] Stream mode
-- [x] Log events using monolog
-- [x] PHP compatibility with 7.2.x, 7.3.x, 7.4.x and 8.0.x
-- [ ] Cap remediation level (ex: for sensitives websites: ban will be capped to captcha)
-- [ ] Retrieve cache items with pagination
-- [ ] Direct CAPI support
-- [ ] Release 1.0.0 version
-- [ ] Support more cache systems (Apcu, Couchbase, Doctrine, Pdo)
+## Licence
 
-Code:
-- [x] Docker dev environment (Dockerized Crowdsec, Redis, Memcached, PHP)
-- [x] Continuous Integration (CI, includes Integration Tests and Super Linter)
-- [x] Integration tests (with TDD)
-- [x] Documented (Static documentation, PHP Doc)
-- [ ] Continuous Delivery (CD)
-- [ ] Load tests (compare performances)
-- [ ] Report Code coverage
-- [ ] Setup Xdebug environment
+[MIT License](https://github.com/crowdsecurity/php-cs-bouncer/blob/main/LICENSE)

composer.json

@@ -1,25 +1,43 @@
 {
-    "name": "crowdsec/bouncer-php-library",
-    "description": "The official PHP client for the CrowdSec LAPI/CAPI",
+    "name": "crowdsec/bouncer",
+    "description": "The official PHP bouncer library for the CrowdSec LAPI/CAPI",
     "type": "library",
-    "license": "MIT License",
+    "license": "MIT",
     "minimum-stability": "stable",
+    "keywords": [
+        "security",
+        "crowdsec",
+        "waf",
+        "middleware",
+        "http",
+        "blocker",
+        "bouncer",
+        "captcha",
+        "geoip",
+        "ip",
+        "ip range"
+    ],
     "autoload": {
         "psr-4": {
             "CrowdSecBouncer\\": "src/"
         }
     },
+    "authors": [
+        {
+            "name": "Lucas Cherifi",
+            "email": "[email protected]"
+        }
+    ],
     "require": {
-        "php": ">=7.1",
+        "php": "^7.2 || ^8.0",
         "symfony/config": "^5.2",
         "symfony/cache": "^5.2",
         "monolog/monolog": "^2.1"
-        
     },
     "require-dev": {
         "predis/predis": "^1.1",
         "bramus/monolog-colored-line-formatter": "^3.0",
         "symfony/var-dumper": "^5.2",
         "phpunit/phpunit": "8.5.13"
     }
-}
+}

docs/configuration.rst renamed to docs/configuration-reference.rst

@@ -1,6 +1,14 @@
 Contribute to this library
 ==========================
 
+### Dev environment
+
+- ✅ Docker dev environment (Dockerized Crowdsec, Redis, Memcached, PHP)
+- ✅ Continuous Integration (CI, includes Integration Tests and Super Linter)
+- ✅ Integration tests (with TDD)
+- ✅ Documented (Static documentation, PHP Doc)
+- ✅ Continuous Delivery (CD)
+
 Guidelines
 ~~~~~~~~~~
 

docs/core-development.rst

@@ -1,9 +1,9 @@
 Environment
 -----------
 
-PHP compatibility matrix: ^5.5.9|>=7.0.8 (same as Symfony 3.4)
+PHP compatibility matrix: >=7.2 (same as Symfony 4.4)
 
-View the usage stats published by packagist (composer) here:
+PHP usage stats published by Packagist (composer) here:
 https://blog.packagist.com/php-versions-stats-2020-1-edition/
 
 Dependencies:

docs/env.rst

@@ -1,41 +1,38 @@
-Technical decisions
-===================
+FAQ
+===
 
 We explain here each important technical decision used to design this
 libary.
 
-We use Symfony/Cache component
-------------------------------
-
-This component is compatible with many cache systems.
+Why using *Symfony/Cache* and *Symfony/Config* component?
+---------------------------------------------------------
 
-This library is tested and maintained under LTS versions.
-
-We use Symfony/Config component
--------------------------------
+The Cache component is compatible with many cache systems.
 
 The Config component provides several classes to help you find, load,
 combine, fill and validate configuration values of any kind, whatever
 their source may be (YAML, XML, INI files, or for instance a database).
 A great job done by this library, tested and maintained under LTS
 versions.
 
-We don't use Guzzle
--------------------
+This library is tested and maintained under LTS versions.
+
+Why not using Guzzle?
+---------------------
 
 The last Guzzle versions remove the User Agent to prevent risks. Since
 LAPI or CAPI need a valid User Agent, we can not use Guzzle to request
 CAPI/LAPI.
 
-We don't use Swagger Codegen
-----------------------------
+Why not using Swagger Codegen?
+------------------------------
 
 We were not able to use this client with easen ex: impossible to get
 JSON data, it's seemd there is a bug with unserialization, we received
 an empty array.
 
-PHP 7.0+ compatibility
-----------------------
+Which PHP compatibility matrix?
+-------------------------------
 
 Why not PHP 5.6?
 

docs/technical-decisions.rst renamed to docs/faq.rst

@@ -15,21 +15,19 @@ Use the bouncer library (live mode)
 
 .. code-block:: php
 
+   /* To get a token: "cscli bouncers add <name-of-your-php-bouncer> */
+   $apiToken = 'YOUR_TOKEN';
 
-   use CrowdSecBouncer\Bouncer;
-   use Symfony\Component\Cache\Adapter\PhpFilesAdapter;
+   /* Select the best cache adapter for your needs (Memcached, Redis, PhpFiles, ...) */
+   $cacheAdapter = new Symfony\Component\Cache\Adapter\PhpFilesAdapter();
 
-   $apiToken = getenv(DEFINE_YOUR_TOKEN);// Good practice: define this secret data in environment variables.
-
-   // Select the best cache adapter for your needs (Memcached, Redis, PhpFiles)
-   // Note: You can try more cache system but we did not test them for now (Apcu, Filesystem, Doctrine, Couchbase, Pdo).
-   // The full list is here: https://symfony.com/doc/current/components/cache.html#available-cache-adapters
-   $cacheAdapter = new PhpFilesAdapter(); 
-
-   $bouncer = new Bouncer();
+   $bouncer = new CrowdSecBouncer\Bouncer();
    $bouncer->configure(['api_token'=> $apiToken], $cacheAdapter);
 
-   $remediation = $bouncer->getRemediationForIp($blockedIp);// Return "ban", "captcha" or "bypass"
+   $remediation = $bouncer->getRemediationForIp($blockedIp);// Return "ban", "captcha" or "bypass".
+
+Note: You can try more cache system but we did not test them for now (Apcu, Filesystem, Doctrine, Couchbase, Pdo).
+The full list is here: https://symfony.com/doc/current/components/cache.html#available-cache-adapters
 
 Use the bouncer library (stream mode)
 ------------------------------------

docs/getting-started.rst

@@ -4,12 +4,12 @@
    getting-started
    how-it-works
    env
-   configuration
+   configuration-reference
    tips
    tests
    contribute
    core-development
-   technical-decisions
+   faq