README

BayLinks Laravel

A modern, type-safe Laravel SDK for the BayLinks URL shortening platform

Features • Installation • Usage • API Reference • Contributing

About

This Laravel package provides an elegant, fluent interface to the BayLinks API - a powerful URL shortening and management platform for modern businesses. Built on top of Saloon PHP, this SDK offers type-safe request/response handling, robust error management, and seamless Laravel integration.

Features

🎯 Type-Safe: Full PHP 8.3+ type safety with PHPStan level 4 analysis
🚀 Modern Architecture: Built on Saloon PHP for elegant HTTP client abstraction
🔒 Secure: Per-request API key authentication with built-in error handling
🧪 Well-Tested: Comprehensive test suite with Pest PHP
📦 Laravel Native: First-class Laravel integration with service provider and facade
🔄 Bulk Operations: Support for bulk URL creation and management
📊 Analytics: Track URL visit records and performance metrics
🎨 PSR Compliant: Follows PSR-1, PSR-2, and PSR-12 coding standards

Requirements

PHP 8.3 or higher
Laravel 10.x, 11.x, or 12.x
Composer 2.x

Installation

Install the package via Composer:

composer require palpalani/baylinks-laravel

Configuration

Publish the configuration file:

php artisan vendor:publish --tag="baylinks-laravel-config"

This creates config/baylinks-laravel.php with the following structure:

return [
    'server' => env('BAYLINKS_SERVER'),

    'api' => [
        'url' => 'api/v1',
        'key' => env('BAYLINKS_API_KEY'),
        'secret' => env('BAYLINKS_API_SECRET'),
    ],
];

Update your .env file:

BAYLINKS_SERVER=https://baylinks.io
BAYLINKS_API_KEY=your_api_key_here
BAYLINKS_API_SECRET=your_api_secret_here

Usage

Basic Examples

Retrieve Account Information

use PalPalani\BayLinks\Facades\BayLinks;

$client = BayLinks::client();
$account = $client->accountDetails()->get('your_api_key');

Create a Single Short URL

use PalPalani\BayLinks\Facades\BayLinks;

$client = BayLinks::client();

$shortUrl = $client->createShortURL()->post('your_api_key', [
    'destination' => 'https://example.com/very-long-url',
    'domain' => 'custom.domain.com', // optional
]);

Create Multiple Short URLs (Bulk)

use PalPalani\BayLinks\Facades\BayLinks;

$client = BayLinks::client();

$bulkUrls = $client->createBulkURL()->post('your_api_key', [
    'destination' => [
        'https://example.com/page-1',
        'https://example.com/page-2',
        'https://example.com/page-3',
    ],
    'domain' => 'custom.domain.com', // optional
    'planet' => 'jupiter', // optional
    'expire' => 0, // optional (0 = never expires)
    'tag' => ['campaign' => 'summer-2024'], // optional metadata
]);

Advanced Usage

Update Short URL Status

$client = BayLinks::client();

$response = $client->updateShortURLStatus()->post('your_api_key', [
    'url_id' => 'abc123',
    'status' => 'inactive',
]);

Retrieve Visit Records

$client = BayLinks::client();

$visitRecords = $client->ShortUrlVisitRecord()->post('your_api_key', [
    'url_id' => 'abc123',
    'from_date' => '2024-01-01',
    'to_date' => '2024-12-31',
]);

Using Dependency Injection

use PalPalani\BayLinks\Factory;

class UrlShortenerService
{
    public function __construct(
        private Factory $bayLinks
    ) {}

    public function shortenUrl(string $url, string $apiKey): mixed
    {
        return $this->bayLinks
            ->createShortURL()
            ->post($apiKey, ['destination' => $url]);
    }
}

Error Handling

use Saloon\Exceptions\Request\FatalRequestException;
use Saloon\Exceptions\Request\RequestException;

try {
    $shortUrl = BayLinks::client()
        ->createShortURL()
        ->post('your_api_key', [
            'destination' => 'https://example.com',
        ]);
} catch (FatalRequestException $e) {
    // Handle fatal errors (network issues, timeouts, etc.)
    Log::error('BayLinks fatal error: ' . $e->getMessage());
} catch (RequestException $e) {
    // Handle API errors (validation, authentication, etc.)
    Log::error('BayLinks API error: ' . $e->getMessage());

    // Access response details
    $statusCode = $e->getStatus();
    $responseBody = $e->getResponse()->body();
}

API Reference

Client Initialization

use PalPalani\BayLinks\Facades\BayLinks;

$client = BayLinks::client();
// or
$client = BayLinks::factory();

Available Methods

Account Operations

Method	Description	Parameters
`accountDetails()->get($apiKey)`	Retrieve account information	`string $apiKey`

URL Operations

Method	Description	Parameters
`createShortURL()->post($apiKey, $data)`	Create a single short URL	`string $apiKey`, `array $data`
`createBulkURL()->post($apiKey, $data)`	Create multiple short URLs	`string $apiKey`, `array $data`
`updateShortURLStatus()->post($apiKey, $data)`	Update URL status	`string $apiKey`, `array $data`
`ShortUrlVisitRecord()->post($apiKey, $data)`	Get visit analytics	`string $apiKey`, `array $data`

Request Payload Schemas

Create Short URL

[
    'destination' => 'https://example.com/page',  // required
    'domain' => 'custom.domain.com',              // optional
]

Create Bulk URLs

[
    'destination' => [                              // required (array of URLs)
        'https://example.com/page-1',
        'https://example.com/page-2',
    ],
    'domain' => 'custom.domain.com',               // optional
    'planet' => 'jupiter',                         // optional
    'expire' => 0,                                 // optional (seconds, 0 = never)
    'tag' => ['key' => 'value'],                   // optional (metadata)
]

Testing

Run the full test suite with Pest:

composer test

Run tests with coverage:

composer test-coverage

Run specific test file:

vendor/bin/pest tests/ExampleTest.php

Run tests with filtering:

vendor/bin/pest --filter=CanCreateShortUrl

Code Quality

Run PHPStan static analysis:

composer analyse

Format code with Laravel Pint:

composer format

Development

Architecture

This package uses Saloon PHP for HTTP client abstraction:

Factory: Main connector extending Saloon\Http\Connector
Resources: Group related API endpoints (AccountResource, CreateShortURLResource)
Requests: Individual API requests extending Saloon\Http\Request
Responses: Transform API responses to DTOs
Objects: Immutable data transfer objects

Adding New Endpoints

Create a new Request class in src/Requests/{Category}/
Create a corresponding Response class in src/Responses/{Category}/
Add a Resource method or create new Resource in src/Resources/
Update the Factory with a new resource method if needed
Write tests in tests/

See CLAUDE.md for detailed development guidelines.

Continuous Integration

This package uses GitHub Actions for automated testing and quality checks:

Workflow	Purpose	Trigger
Tests	Run Pest tests across PHP 8.3-8.4, Laravel 11-12, Ubuntu/Windows	Push, PR
PHPStan	Static analysis at level 4	Push, PR
Code Coverage	Track test coverage with Codecov	Push, PR
Security Scan	Composer audit, dependency review, SBOM generation	Push, PR, Weekly
Code Style	Auto-fix with Laravel Pint	Push (branches only)
PR Quality	Validate composer.json, check for debug statements	PR only

All workflows use Composer caching for faster builds and concurrency controls to prevent redundant runs.

Troubleshooting

Common Issues

"Class 'BayLinks' not found"

Make sure you've published the service provider:

php artisan config:clear
php artisan cache:clear
composer dump-autoload

Authentication Errors

Verify your API key is correct and active:

// Test connection
try {
    $account = BayLinks::client()->accountDetails()->get('your_api_key');
    dump($account);
} catch (\Exception $e) {
    echo $e->getMessage();
}

SSL Certificate Issues

If you encounter SSL errors in development:

// In config/baylinks-laravel.php (development only!)
// Note: Never disable SSL verification in production

Changelog

Please see CHANGELOG for recent changes and version history.

Contributing

We welcome contributions! Here's how you can help:

Getting Started

Fork the repository
Create a feature branch: git checkout -b feature/my-new-feature
Make your changes and commit: git commit -am 'Add new feature'
Push to the branch: git push origin feature/my-new-feature
Submit a pull request

Development Guidelines

Follow PSR-1, PSR-2, and PSR-12 coding standards
Write tests for new features (we use Pest)
Ensure PHPStan passes at level 4: composer analyse
Format code with Pint: composer format
Update documentation for API changes
Add entries to CHANGELOG.md

Running Tests

# Install dependencies
composer install

# Run tests
composer test

# Run static analysis
composer analyse

# Format code
composer format

Pull Request Checklist

Tests pass (composer test)
Static analysis passes (composer analyse)
Code is formatted (composer format)
Documentation is updated
CHANGELOG.md is updated

Security

If you discover any security-related issues, please email palani.p@gmail.com instead of using the issue tracker. All security vulnerabilities will be promptly addressed.

Credits

palPalani - Creator & Maintainer
Prasanth - Core Developer
All Contributors - Community Contributors

License

The MIT License (MIT). Please see License File for more information.

⬆ Back to Top

Made with ❤️ by palPalani

palpalani / baylinks-laravel

Maintainers

Details