README

A PHP SDK for integrating with the Markup.ai content governance platform. This library provides a clean, PSR-compliant interface for accessing Markup.ai's style checking, content validation, and automated rewriting capabilities.

Installation

Install the package via Composer:

composer require markupai/php-sdk

Laravel Integration

When used inside a Laravel 9+ application the package is auto-discovered. Configure your API token by setting MARKUPAI_API_TOKEN in the environment (or editing config/markupai.php after publishing).

php artisan vendor:publish --tag=markupai-config

Access the client through dependency injection or the optional facade:

use MarkupAI\MarkupAiClient;
use MarkupAI\Laravel\Facades\MarkupAi;

// Constructor injection
public function __construct(MarkupAiClient $client)
{
    $this->client = $client;
}

// Facade usage
$styleGuides = MarkupAi::styleGuides()->list();

Requirements

PHP 8.1 or higher
PSR-18 HTTP client implementation (e.g., Guzzle)
PSR-7 HTTP message implementation

Quick Start

<?php

require_once 'vendor/autoload.php';

use MarkupAI\MarkupAiClient;

// Initialize the client
$client = new MarkupAiClient('your-api-token');

// List all style guides
$styleGuides = $client->styleGuides()->list();

// Create a style check with file upload
$styleCheck = $client->styleChecks()->createWithFile([
    'dialect' => 'american_english',
    'style_guide' => 'your-style-guide-id'
], '/path/to/your/document.txt');

// Get style suggestions with file upload
$suggestions = $client->styleSuggestions()->createWithFile([
    'dialect' => 'american_english',
    'style_guide' => 'your-style-guide-id',
    'tone' => 'professional'
], '/path/to/your/document.txt');

// Generate a style rewrite with file upload
$rewrite = $client->styleRewrites()->createWithFile([
    'dialect' => 'american_english',
    'style_guide' => 'your-style-guide-id',
    'tone' => 'professional'
], '/path/to/your/document.txt');

API Reference

Style Guides

// List all style guides
$styleGuides = $client->styleGuides()->list();

// Create a new style guide
$styleGuide = $client->styleGuides()->create([
    'name' => 'My Style Guide',
    'description' => 'A custom style guide'
]);

// Get a specific style guide
$styleGuide = $client->styleGuides()->get('style-guide-id');

// Update a style guide
$styleGuide = $client->styleGuides()->update('style-guide-id', [
    'name' => 'Updated Style Guide'
]);

// Delete a style guide
$client->styleGuides()->delete('style-guide-id');

Style Checks

// Create a style check with file upload (required)
$styleCheck = $client->styleChecks()->createWithFile([
    'dialect' => 'american_english',
    'style_guide' => 'your-style-guide-id'
], '/path/to/document.txt');

// Get style check results
$styleCheck = $client->styleChecks()->get('style-check-id');

// Check if completed
if ($styleCheck->isCompleted()) {
    $results = $styleCheck->getResults();
    // Access issues and scores
    $issues = $results['original']['issues'] ?? [];
    $qualityScore = $results['original']['scores']['quality']['score'] ?? null;
}

Style Suggestions

// Create style suggestions with file upload
$suggestions = $client->styleSuggestions()->createWithFile([
    'dialect' => 'american_english',
    'style_guide' => 'your-style-guide-id',
    'tone' => 'professional'
], '/path/to/document.txt');

// Get suggestions
$suggestions = $client->styleSuggestions()->get('suggestion-id');

if ($suggestions->isCompleted()) {
    $suggestionData = $suggestions->getSuggestions();
}

Style Rewrites

// Create a style rewrite with file upload
$rewrite = $client->styleRewrites()->createWithFile([
    'dialect' => 'american_english',
    'style_guide' => 'your-style-guide-id',
    'tone' => 'professional'
], '/path/to/document.txt');

// Get rewritten content
$rewrite = $client->styleRewrites()->get('rewrite-id');

if ($rewrite->isCompleted()) {
    $rewrittenContent = $rewrite->getRewrittenContent();
}

Configuration

Custom HTTP Client

You can provide your own PSR-18 HTTP client:

use GuzzleHttp\Client as GuzzleClient;
use Nyholm\Psr7\Factory\Psr17Factory;

$httpClient = new GuzzleClient();
$factory = new Psr17Factory();

$client = new MarkupAiClient(
    token: 'your-api-token',
    httpClient: $httpClient,
    requestFactory: $factory,
    streamFactory: $factory
);

Custom Base URL

$client = new MarkupAiClient(
    token: 'your-api-token',
    baseUrl: 'https://custom-api.markup.ai/v1'
);

Error Handling

The SDK provides specific exception types for different error conditions:

use MarkupAI\Exceptions\AuthenticationException;
use MarkupAI\Exceptions\ValidationException;
use MarkupAI\Exceptions\RateLimitException;
use MarkupAI\Exceptions\ServerException;

try {
    $styleGuides = $client->styleGuides()->list();
} catch (AuthenticationException $e) {
    // Handle authentication errors (401)
    echo 'Invalid API token: ' . $e->getMessage();
} catch (ValidationException $e) {
    // Handle validation errors (422)
    echo 'Validation error: ' . $e->getMessage();
} catch (RateLimitException $e) {
    // Handle rate limiting (429)
    echo 'Rate limit exceeded: ' . $e->getMessage();
} catch (ServerException $e) {
    // Handle server errors (500+)
    echo 'Server error: ' . $e->getMessage();
}

Development

Running Tests

# Run all tests
composer test

# Run tests with coverage
composer test-coverage

# Run static analysis
composer phpstan

# Fix code style
composer cs-fix

# Check code style
composer cs-check

Requirements for Development

# Install development dependencies
composer install

# Install suggested packages for HTTP client
composer require guzzlehttp/guzzle nyholm/psr7

Running Integration Tests

Integration tests require a valid Markup.ai API token:

# Copy the example environment file
cp .env.testing.example .env.testing

# Edit .env.testing and add your API token
# MARKUPAI_API_TOKEN=your_actual_token_here

# Run all tests (integration tests will be skipped if no token is provided)
composer test

# Run only unit tests (no API token required)
vendor/bin/phpunit tests/Unit/

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

markupai / php-sdk

Maintainers

Details