aqtivite / php

v0.2.0 2026-10-04 13:30 UTC

Requires

• php: ^8.4
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• Mehmet ÖĞMEN

• php
• rest
• api
• sdk
• aqtivite

Published on Packagist.org on 2026-10-04 13:32 UTC

README

Aqtivite REST API için resmi PHP SDK'sı.

Gereksinimler

• PHP 8.4+
• Composer

Kurulum

composer require aqtivite/php

Hızlı Başlangıç

use Aqtivite\Php\Aqtivite;

$client = new Aqtivite('client-id', 'client-secret', ['admin:tickets:read']);

$response = $client->user()->events()->get();

Yapılandırma

Test Modu

$client = new Aqtivite('client-id', 'client-secret');
$client->testMode(); // api.test.aqtivite.com.tr adresine bağlanır

Özel API Adresi

$client->setBaseUrl('https://custom-api.example.com');

Özel HTTP Transport

SDK varsayılan olarak Guzzle kullanır. İsterseniz setTransport() ile kendi HTTP transport'unuzu kullanabilirsiniz (ör: Laravel Http).

use Aqtivite\Php\Contracts\HttpTransportInterface;
use Aqtivite\Php\Http\TransportResponse;

class LaravelTransport implements HttpTransportInterface
{
    public function send(string $method, string $url, array $options = []): TransportResponse
    {
        $response = Http::withHeaders($options['headers'] ?? [])
            ->send($method, $url, $options);

        return new TransportResponse(
            statusCode: $response->status(),
            body: $response->json() ?? [],
        );
    }
}

$client = new Aqtivite('client-id', 'client-secret');
$client->setTransport(new LaravelTransport());

Kimlik Doğrulama

SDK, API'ye OAuth2 client_credentials grant'i ile bağlanır. Her servis API'de kendi client'ı ile tanımlıdır; token bir kullanıcıyı değil client'ın kendisini temsil eder ve yalnızca client'a tanınan scope'ları taşır.

$client = new Aqtivite('client-id', 'client-secret', [
    'admin:venues:read',
    'admin:events:create',
]);

Scope'lar sonradan da verilebilir:

$client->setScopes(['admin:tickets:read']);

Token ilk istekte alınır. Süresinin dolmasına 60 saniye kala ya da API 401 döndürdüğünde yenisi alınır. Token'ı elle almak için:

$token = $client->issueToken();

Mevcut Token ile Başlama

Daha önce saklanmış bir token yüklenebilir. Süresi dolmuşsa SDK yenisini alır.

$client->setToken('access-token', new DateTimeImmutable('2026-10-05 12:00:00'));

Token Bilgisi

$token = $client->getToken();
$token->accessToken;
$token->expiresAt;   // DateTimeImmutable|null
$token->tokenType;
$token->isExpired();

Yeni Token Alındığında Bildirim

Yeni bir token alındığında callback tetiklenir. Bu sayede token kalıcı olarak saklanabilir.

$client->onTokenIssued(function (Token $token) {
    Cache::put('aqtivite_token', [
        'access_token' => $token->accessToken,
        'expires_at' => $token->expiresAt?->format(DATE_ATOM),
    ]);
});

Kullanım

User Modülü

// Kullanıcılar
$client->user()->users()->get();                                          // Listele
$client->user()->users()->get(filter: ['name' => 'mehmet']);              // Filtrele
$client->user()->users()->get(query: ['page' => 2, 'length' => 20]);    // Sayfalama
$client->user()->users()->find('mehmet.ogmen');                           // Detay
$client->user()->users()->events('mehmet.ogmen');                         // Kullanıcının etkinlikleri

// Etkinlikler
$client->user()->events()->get();                                         // Listele
$client->user()->events()->get(query: ['order' => 'price[desc]']);
$client->user()->events()->find('etkinlik-slug');        // Detay

// Etkinlik Kategorileri
$client->user()->eventCategories()->get();
$client->user()->eventCategories()->find(1);

// Seanslar
$client->user()->occurrences()->get(filter: ['event_id' => 6999]);
$client->user()->occurrences()->find(166);

// Organizatörler
$client->user()->organizers()->get();
$client->user()->organizers()->find('aqtivite');

// Arama & Ağ
$client->user()->search('aqtivite');
$client->user()->network();

Common Modülü

// Mekanlar
$client->common()->venues()->get();
$client->common()->venues()->find(1);

// Salonlar
$client->common()->halls()->get();
$client->common()->halls()->find(1);

// Para Birimleri
$client->common()->currencies()->get();

// Bölgeler
$client->common()->regions()->get();
$client->common()->regions()->find(1);

// Ülkeler
$client->common()->countries()->get();
$client->common()->countries()->find(1);

// İller
$client->common()->provinces()->get();
$client->common()->provinces()->find(1);

// İlçeler
$client->common()->districts()->get(filter: ['province_id' => 3, 'name' => 'ala']);
$client->common()->districts()->get(                    // Filter + sayfalama
    filter: ['province_id' => 3],
    query: ['page' => 1],
);
$client->common()->districts()->find(1);

// Mahalleler
$client->common()->neighborhoods()->get();
$client->common()->neighborhoods()->find(1);

Response Yapısı

Standart Response

$response = $client->user()->users()->find('mehmet.ogmen');

$response->successful();       // true
$response->failed();           // false
$response->data;               // Veri (array veya object)
$response->elapsedTime;        // Süre

Sayfalanmış Response

$response = $client->user()->users()->get();

$response->data;               // Veri listesi
$response->total;              // Toplam kayıt
$response->currentPage;        // Mevcut sayfa
$response->lastPage;           // Son sayfa
$response->from;               // Başlangıç
$response->to;                 // Bitiş
$response->hasNextPage();      // Sonraki sayfa var mı?
$response->hasPreviousPage();  // Önceki sayfa var mı?

Hata Yönetimi

use Aqtivite\Php\Exceptions\AuthenticationException;
use Aqtivite\Php\Exceptions\ApiException;
use Aqtivite\Php\Exceptions\AqtiviteException;

try {
    $response = $client->user()->users()->get();
} catch (AuthenticationException $e) {
    // Kimlik doğrulama hatası
    echo $e->getMessage();
} catch (ApiException $e) {
    // API hatası
    echo $e->getMessage();
    echo $e->getCode();       // HTTP hata kodu
    echo $e->errorType;       // Hata tipi (ör: "app")
} catch (AqtiviteException $e) {
    // Genel SDK hatası
    echo $e->getMessage();
}

Lisans

MIT