Skip to content

CLAUDE.md

Latest commit

 

History

History
144 lines (112 loc) · 5.23 KB

CLAUDE.md

File metadata and controls

144 lines (112 loc) · 5.23 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

This is the PHP SDK for the Smartling Translation API. It provides a PHP client library for interacting with Smartling's translation management platform, allowing developers to upload files for translation, download translated content, manage translation jobs, and access other Smartling API features.

Development Commands

Install Dependencies

composer install

Run All Tests

Tests require Smartling API credentials as environment variables:

account_uid=<account_uid> project_id=<project_id> user_id=<user_id> user_key=<user_key> ./vendor/bin/phpunit

Run Specific Test Suites

# Unit tests only
./vendor/bin/phpunit --testsuite unit

# Functional tests only (requires API credentials)
account_uid=<account_uid> project_id=<project_id> user_id=<user_id> user_key=<user_key> ./vendor/bin/phpunit --testsuite functional

Run Individual Test Files

./vendor/bin/phpunit tests/unit/SomeTest.php

Architecture

Core Components

BaseApiAbstract (src/BaseApiAbstract.php)

  • Abstract base class for all API clients
  • Handles HTTP communication via Guzzle
  • Manages authentication via AuthApiInterface
  • Implements automatic token refresh on 401 errors
  • Provides logging support via PSR-3 LoggerInterface
  • Standardizes error handling and response processing
  • All API classes extend this base

Authentication Flow

  • AuthTokenProvider (src/AuthApi/) implements AuthApiInterface
  • Manages OAuth access tokens and refresh tokens with automatic expiration handling
  • Token refresh happens automatically when expired or on 401 responses
  • All API clients receive an auth provider instance and use it to authenticate requests

API Client Pattern Each Smartling API endpoint has a dedicated API class:

  • FileApi - File upload, download, and management
  • JobsApi - Translation job management
  • BatchApi / BatchApiV2 - Batch operations
  • ContextApi - Visual context and screenshots
  • ProjectApi - Project information
  • AuditLogApi - Audit logs
  • ProgressTrackerApi - Translation progress tracking
  • TranslationRequestsApi - Translation request management
  • DistributedLockServiceApi - Distributed locking

Parameter Objects

  • Located in */Params/ directories under each API module
  • Implement ParameterInterface or extend BaseParameters
  • Provide type-safe parameter building for API methods
  • Example: UploadFileParameters, CreateJobParameters, DownloadFileParameters

Directory Structure

src/
├── BaseApiAbstract.php       # Base class for all API clients
├── AuthApi/                   # Authentication provider
├── File/                      # File API (upload/download)
├── Jobs/                      # Jobs API
├── Batch/                     # Batch operations (v1 and v2)
├── Context/                   # Visual context API
├── Project/                   # Project information API
├── AuditLog/                  # Audit logging API
├── ProgressTracker/           # Progress tracking API
├── TranslationRequests/       # Translation requests API
├── DistributedLockService/    # Distributed lock service
├── Parameters/                # Base parameter classes
└── Exceptions/                # Custom exceptions

tests/
├── unit/                      # Unit tests (no API calls)
└── functional/                # Functional tests (require API credentials)

examples/                      # Usage examples for each API

API Client Instantiation Pattern

All API clients follow this factory pattern:

$authProvider = AuthTokenProvider::create($userIdentifier, $userSecretKey);
$api = SomeApi::create($authProvider, $projectId, $logger);

Each API class:

  1. Defines its own ENDPOINT_URL constant
  2. Provides a static create() factory method
  3. Initializes an HTTP client via BaseApiAbstract::initializeHttpClient()
  4. Sets the auth provider via setAuth()

Error Handling

  • SmartlingApiException is thrown for all API errors
  • Errors contain structured error information from the API response
  • 401 errors trigger automatic token refresh and retry
  • Sensitive data (tokens, credentials) is redacted from logs

Logging

  • All API clients accept an optional PSR-3 LoggerInterface
  • Requests and responses are logged for debugging
  • Sensitive data is automatically redacted in logs

PHP Version Support

  • PHP 7.3+ and PHP 8.x
  • Uses PSR-4 autoloading
  • Requires Guzzle 6.x or 7.x for HTTP client
  • Requires PSR Log 1.x or 3.x for logging

Testing Strategy

  • Unit tests (tests/unit/) - Test logic without making actual API calls
  • Functional tests (tests/functional/) - Integration tests that call the real Smartling API
  • Functional tests require valid Smartling credentials passed as environment variables
  • Test resources are stored in tests/resources/

Examples

The examples/ directory contains working examples for each API:

  • Run with: php file-example.php --project-id=XXX --user-id=XXX --secret-key=XXX
  • Each example demonstrates common operations for that API
  • Examples are self-contained and include inline documentation