README

The simple way to build REST APIs in PHP.

Installation

composer require baukasten/webservice

Requirements

PHP 8.0 or higher
Required PHP extensions:
- dom
- json
- libxml
- mbstring
- tokenizer
- xml
- xmlwriter

Basic Usage

<?php
// index.php

use Baukasten\Webservice\Controller\DemoController;
use Baukasten\Webservice\Router;

// Autoload dependencies
require_once __DIR__ . '/vendor/autoload.php';

// Router handles everything from capturing the request to sending out responses
Router::handleRequest([DemoController::class]);

Testing

Running Tests Locally

We provide a convenient shell script to run tests with various options:

# Make the scripts executable first
chmod +x run-tests.sh
chmod +x generate-reports.sh

# Run all tests
./run-tests.sh

# Run a specific test suite
./run-tests.sh --testsuite EndToEnd

# Run tests matching a specific pattern
./run-tests.sh --filter DemoControllerTest

# Generate code coverage report in HTML format
./run-tests.sh --coverage-html coverage

# Show help with all available options
./run-tests.sh --help

Generating Test Reports

To generate comprehensive test and coverage reports:

./generate-reports.sh

This will create various reports in the reports directory:

HTML Coverage Report: reports/coverage/index.html
Clover XML Coverage: reports/coverage.xml
Text Coverage: reports/coverage.txt
TestDox HTML: reports/testdox.html
TestDox Text: reports/testdox.txt
JUnit XML: reports/junit.xml

Running Tests with Docker

We provide a simple Docker-based approach to run PHPUnit tests in an isolated environment with all dependencies pre-installed:

# Make the script executable first
chmod +x run-phpunit.sh

# Run all tests with default options
./run-phpunit.sh

# Run a specific test suite
./run-phpunit.sh --testsuite EndToEnd

# Run tests matching a specific pattern
./run-phpunit.sh --filter DemoControllerTest

# Generate code coverage report in text format
./run-phpunit.sh --coverage-text

# Generate comprehensive test reports
./run-phpunit.sh --generate-reports

The script automatically builds the Docker image if needed and mounts the reports directory. All reports will be available in the reports directory.

CI/CD Integration

The project includes configuration files for popular CI/CD platforms:

GitHub Actions: Configuration in .github/workflows/php-tests.yml
GitLab CI: Configuration in .gitlab-ci.yml

These configurations automatically run tests on PHP 8.0, 8.1, and 8.2, and generate code coverage reports.

For more detailed information about testing, see tests/README.md.

Semantic Release Tokens

For GitLab CI/CD:

Create a Personal Access Token (https://gitlab.com/-/user_settings/personal_access_tokens)
Add the token as 'CUSTOM_PUSH_TOKEN' in your project's CI/CD variables

License

This project is licensed under the MIT License - see the LICENSE file for details.

baukasten / webservice

Maintainers

Details