README

A lightweight and flexible proxy layer for making API requests using Symfony's HTTP client components.

Requirements

PHP >= 8.1
Symfony/HttpClient (6.4+)
Symfony/Cache (6.4+)
Symfony/DotEnv (6.4+)
Symfony/Serializer (6.4+)

Installation

composer require insideapps/api-proxy

Features

Bearer token authentication
Automatic token refresh
Request caching
Support for all common HTTP methods (GET, POST, PUT, DELETE)
Configurable timeout and retry options

Usage

Basic Setup

Bearer Token Authentication

use InsideApps\ApiProxy\Factory\ProxyFactory;

// Create a client with Bearer token authentication
$apiClient = ProxyFactory::bearerClient(
    baseUrl: 'https://api.example.com/',
    authUrl: 'https://api.example.com/auth',
    credentialItems: [
        'username' => 'your_username',
        'password' => 'your_password'
    ]
);

// Make a simple GET request
$response = $apiClient->get('users/123');

// Access response data
$userData = $response->toArray();

Caching Responses

Enable caching for GET requests to improve performance:

// Parameters:
// 1. Endpoint
// 2. Enable cache (boolean)
// 3. Cache lifetime in seconds (default: 3600)
$response = $apiClient->get('products', true, 60);

HTTP Methods

The client supports all common HTTP methods:

// GET request
$response = $apiClient->get('users');

// POST request with data
$response = $apiClient->post('users', [
    'name' => 'John Doe',
    'email' => 'john@example.com'
]);

// PUT request
$response = $apiClient->put('users/123', [
    'name' => 'Updated Name'
]);

// DELETE request
$response = $apiClient->delete('users/123');

Advanced Configuration

You can configure additional options when creating the client:

$apiClient = ProxyFactory::bearerClient(
    baseUrl: 'https://api.example.com/',
    authUrl: 'https://api.example.com/auth',
    credentialItems: [
        'username' => 'your_username',
        'password' => 'your_password'
    ],
    options: [
        'timeout' => 30,
        'max_retries' => 3
    ]
);

Symfony Integration

Environment Variables

Add the required environment variables to your .env file:

# .env
# Common API settings
API_BASE_URL=https://api.example.com
API_AUTH_URL=https://api.example.com/auth
API_USERNAME=your_username
API_PASSWORD=your_password

# Multiple API endpoints can be configured
USERS_API_BASE_URL=https://users-api.example.com
USERS_API_AUTH_URL=https://users-api.example.com/auth
USERS_API_USERNAME=users_username
USERS_API_PASSWORD=users_password

PRODUCTS_API_BASE_URL=https://products-api.example.com
PRODUCTS_API_AUTH_URL=https://products-api.example.com/auth
PRODUCTS_API_USERNAME=products_username
PRODUCTS_API_PASSWORD=products_password

Service Configuration

You can easily integrate the API Proxy into your Symfony application by defining repositories as services in your services.yaml file:

# config/services.yaml
parameters:
    # Define common API parameters
    app.api.base_url: '%env(API_BASE_URL)%'
    app.api.auth_url: '%env(API_AUTH_URL)%'
    app.api.username: '%env(API_USERNAME)%'
    app.api.password: '%env(API_PASSWORD)%'
    
    # Define specific API parameters for different endpoints
    app.users_api.base_url: '%env(USERS_API_BASE_URL)%'
    app.users_api.auth_url: '%env(USERS_API_AUTH_URL)%'
    app.users_api.username: '%env(USERS_API_USERNAME)%'
    app.users_api.password: '%env(USERS_API_PASSWORD)%'
    
    app.products_api.base_url: '%env(PRODUCTS_API_BASE_URL)%'
    app.products_api.auth_url: '%env(PRODUCTS_API_AUTH_URL)%'
    app.products_api.username: '%env(PRODUCTS_API_USERNAME)%'
    app.products_api.password: '%env(PRODUCTS_API_PASSWORD)%'

services:
    # Factory service
    InsideApps\ApiProxy\Factory\ProxyFactory:
        public: true
        
    # Abstract repository service
    App\Repository\AbstractApiRepository:
        abstract: true
        
    # User repository service
    App\Repository\UserRepository:
        arguments:
            $baseUrl: '%app.users_api.base_url%'
            $authUrl: '%app.users_api.auth_url%'
            $username: '%app.users_api.username%'
            $password: '%app.users_api.password%'
            $serializer: '@serializer'
            $endpoint: 'users'
            
    # Product repository service
    App\Repository\ProductRepository:
        arguments:
            $baseUrl: '%app.products_api.base_url%'
            $authUrl: '%app.products_api.auth_url%'
            $username: '%app.products_api.username%'
            $password: '%app.products_api.password%'
            $serializer: '@serializer'
            $endpoint: 'products'

Creating an Abstract Repository

Here's an example of creating an abstract repository class that uses the API Proxy with Symfony's Serializer component:

<?php

namespace App\Repository;

use InsideApps\ApiProxy\ApiProxy;
use InsideApps\ApiProxy\Factory\ProxyFactory;
use Symfony\Component\Serializer\SerializerInterface;

/**
 * Abstract API repository with common functionality
 */
abstract class AbstractApiRepository
{
    protected ApiProxy $apiClient;
    protected SerializerInterface $serializer;
    protected string $endpoint;
    protected string $entityClass;
    
    /**
     * Create a new repository instance with API client
     */
    public function __construct(
        string $baseUrl,
        string $authUrl,
        string $username,
        string $password,
        SerializerInterface $serializer,
        string $endpoint,
        string $entityClass = null
    ) {
        // Create the API client in the constructor
        $this->apiClient = ProxyFactory::bearerClient(
            baseUrl: $baseUrl,
            authUrl: $authUrl,
            credentialItems: [
                'username' => $username,
                'password' => $password
            ]
        );
        
        $this->serializer = $serializer;
        $this->endpoint = $endpoint;
        $this->entityClass = $entityClass ?? 'App\\Entity\\' . ucfirst(substr($endpoint, -1) === 's' ? substr($endpoint, 0, -1) : $endpoint);
    }
    
    /**
     * Get all resources
     */
    public function findAll(bool $useCache = true, int $cacheLifetime = 3600): array
    {
        $response = $this->apiClient->get($this->endpoint, $useCache, $cacheLifetime);
        return $this->serializer->deserialize($response, $this->entityClass . '[]', 'json');
    }
    
    /**
     * Find a resource by ID
     */
    public function find(int $id, bool $useCache = true, int $cacheLifetime = 3600): ?object
    {
        $response = $this->apiClient->get($this->endpoint . '/' . $id, $useCache, $cacheLifetime);
        return $this->serializer->deserialize($response, $this->entityClass, 'json');
    }
    
    /**
     * Create a new resource
     */
    public function create(array $data): object
    {
        $response = $this->apiClient->post($this->endpoint, $data);
        return $this->serializer->deserialize($response, $this->entityClass, 'json');
    }
    
    /**
     * Update an existing resource
     */
    public function update(int $id, array $data): object
    {
        $response = $this->apiClient->put($this->endpoint . '/' . $id, $data);
        return $this->serializer->deserialize($response, $this->entityClass, 'json');
    }
    
    /**
     * Delete a resource
     */
    public function delete(int $id): bool
    {
        $this->apiClient->delete($this->endpoint . '/' . $id);
        return true;
    }
}

Implementing a Concrete Repository

<?php

namespace App\Repository;

/**
 * User API repository
 */
class UserRepository extends AbstractApiRepository
{
    // You can override methods or add custom ones specific to users
    
    /**
     * Find users by role
     */
    public function findByRole(string $role, bool $useCache = true): array
    {
        $response = $this->apiClient->get($this->endpoint . '/role/' . $role, $useCache);
        return $this->serializer->deserialize($response, $this->entityClass . '[]', 'json');
    }
}

Using the Repository in a Controller

<?php

namespace App\Controller;

use App\Repository\UserRepository;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;

class UserController extends AbstractController
{
    private UserRepository $userRepository;

    public function __construct(UserRepository $userRepository)
    {
        $this->userRepository = $userRepository;
    }

    #[Route('/api/users', name: 'api_users_index', methods: ['GET'])]
    public function index(): JsonResponse
    {
        $users = $this->userRepository->findAll();
        return $this->json($users);
    }

    #[Route('/api/users/{id}', name: 'api_users_show', methods: ['GET'])]
    public function show(int $id): JsonResponse
    {
        $user = $this->userRepository->find($id);
        return $this->json($user);
    }
    
    #[Route('/api/users', name: 'api_users_create', methods: ['POST'])]
    public function create(Request $request): JsonResponse
    {
        $data = json_decode($request->getContent(), true);
        $user = $this->userRepository->create($data);
        return $this->json($user, 201);
    }
    
    #[Route('/api/users/role/{role}', name: 'api_users_by_role', methods: ['GET'])]
    public function findByRole(string $role): JsonResponse
    {
        $users = $this->userRepository->findByRole($role);
        return $this->json($users);
    }
}

License

MIT

insideapps / api-proxy

Maintainers

Details