README

Mebularts Shopier PHP SDK

Shopier API işlemlerini PHP projelerine Composer ile hızlı, güvenli ve sürdürülebilir biçimde eklemek için framework bağımsız PHP SDK’sı.

Warning

Bu paket alpha aşamasındadır. API yüzeyi değişebilir. Canlı ödeme ve webhook akışlarında kullanmadan önce kendi Shopier hesabınızda kapsamlı test yapmanız önerilir.

Note

mebularts/shopier, Mebularts tarafından geliştirilen bağımsız bir açık kaynak PHP paketidir. Shopier ile resmi ortaklık, temsilcilik veya bağlılık iddiası taşımaz.

Neden Mebularts Shopier PHP SDK?

Shopier API entegrasyonlarında yalnızca HTTP isteği göndermek yeterli değildir. Ödeme akışında ürün oluşturma, yönlendirme, webhook yönetimi, ödeme doğrulama, tekrar eden bildirimleri ele alma ve hata senaryoları birlikte düşünülmelidir.

Bu paket; Shopier API işlemlerini daha düzenli bir yapıya taşırken, kendi uygulamanızdaki sipariş, stok, sepet, e-posta ve kargo akışlarını kontrolünüzde tutmanıza yardımcı olur.

Öne Çıkanlar

Alan	Sağlanan yapı
Kurulum	Composer ile tek komut
Uyum	Framework bağımsız PHP 8.1+
API	Ürün, sipariş, bakiye, iade ve webhook kaynakları
Checkout	Sepetten dinamik Shopier ürünü oluşturma ve ödeme URL’si alma
Doğrulama	PAT ile API recheck ve isteğe bağlı signature doğrulama
Veri güvenliği	Typed DTO, merkezi exception yapısı ve hassas veri maskeleme
Geliştirici deneyimi	CLI komutları, örnekler, test ve static analysis altyapısı

Gereksinimler

PHP 8.1 veya üzeri
ext-json
Shopier API erişimi için geçerli bir Personal Access Token (PAT)
Signature doğrulaması kullanacaksanız webhook secret

Kurulum

composer require mebularts/shopier

Ardından Composer autoloader’ını projenize dahil edin:

<?php

require __DIR__ . '/vendor/autoload.php';

Ortam Değişkenleri

SHOPIER_PAT=your_personal_access_token
SHOPIER_BASE_URI=https://api.shopier.com/v1
SHOPIER_WEBHOOK_VALIDATION_MODE=auto

İsteğe bağlı değerler:

SHOPIER_WEBHOOK_SECRET=
SHOPIER_WEBHOOK_SIGNATURE_ENCODING=hex
SHOPIER_TIMEOUT_SECONDS=30
SHOPIER_CONNECT_TIMEOUT_SECONDS=10
SHOPIER_DEBUG=false

Token, secret ve canlı müşteri verilerini .env dışına çıkarmayın; GitHub repository’sine veya public issue’lara eklemeyin.

Hızlı Başlangıç

<?php

require __DIR__ . '/vendor/autoload.php';

use Mebularts\Shopier\Config\ShopierConfig;
use Mebularts\Shopier\Shopier;

$shopier = Shopier::configure(
    ShopierConfig::fromArray([
        'access_token' => $_ENV['SHOPIER_PAT'],
        'base_uri' => $_ENV['SHOPIER_BASE_URI'] ?? 'https://api.shopier.com/v1',
    ])
);

Ortam değişkenlerini doğrudan kullanmak için:

$shopier = Shopier::fromEnv();

Bakiye ve Sipariş İşlemleri

Bakiye Sorgulama

$balance = $shopier->balance()->get();

foreach ($balance->items as $item) {
    echo $item->currency . ': ' . $item->amount . PHP_EOL;
}

Siparişleri Listeleme

$orders = $shopier->orders()->list([
    'limit' => 10,
]);

foreach ($orders->items as $order) {
    echo $order->id . ' - ' . ($order->paymentStatus ?? 'unknown') . PHP_EOL;
}

Sipariş Detayı

$order = $shopier->orders()->get('shopier-order-id');

if ($order->isPaid()) {
    // Sipariş Shopier tarafında ödenmiş olarak doğrulandı.
}

Dinamik Shopier Ürün Ödeme Akışı

Bu akış, kendi sisteminizde pending sipariş oluşturduktan sonra sepet toplamına göre Shopier tarafında dinamik bir ürün oluşturmanızı ve kullanıcıyı o ürünün ödeme sayfasına yönlendirmenizi sağlar.

Müşteri checkout başlatır
        ↓
Kendi sisteminizde pending sipariş oluşur
        ↓
Shopier’de dinamik ürün oluşturulur
        ↓
Ürün ID + ödeme URL’si kendi payment session kaydınıza alınır
        ↓
Müşteri Shopier ödeme sayfasına yönlendirilir
        ↓
Webhook / API recheck ile ödeme doğrulanır
        ↓
Kendi merkezi “paid” handler’ınız çalışır

Important

Dinamik ürün oluşturulması, ödemenin tamamlandığı anlamına gelmez. Local siparişi yalnızca webhook veya API recheck sonucu doğrulanmış ödeme varsa tamamlayın.

Tek Ürünlü Sepet

use Mebularts\Shopier\Checkout\CartItemData;
use Mebularts\Shopier\Checkout\DynamicProductCheckoutRequest;
use Mebularts\Shopier\Support\Money;

$result = $shopier->checkout()->createDynamicProduct(
    new DynamicProductCheckoutRequest(
        reference: 'ORD-EXAMPLE-1001',
        total: Money::from('1299.90', 'TRY'),
        items: [
            new CartItemData(
                title: 'Sample T-Shirt',
                quantity: 1,
                unitPrice: Money::from('1299.90', 'TRY'),
                variant: 'Black / XL',
                imageUrl: 'https://example.com/products/sample-tshirt.jpg'
            ),
        ],
        defaultImageUrl: 'https://example.com/assets/default-product.jpg'
    )
);

// Bu bilgileri kendi payment session tablonuza kaydedin.
$session = [
    'reference' => $result->reference,
    'shopier_product_id' => $result->productId,
    'shopier_redirect_url' => $result->redirectUrl,
    'expected_amount' => $result->expectedAmount,
    'expected_currency' => $result->expectedCurrency,
    'status' => 'awaiting_shopier_payment',
];

// Düz PHP yönlendirmesi:
header('Location: ' . $result->redirectUrl, true, 303);
exit;

Çok Ürünlü Sepet

$result = $shopier->checkout()->createDynamicProduct(
    new DynamicProductCheckoutRequest(
        reference: 'ORD-EXAMPLE-1002',
        total: Money::from('2499.80', 'TRY'),
        items: [
            new CartItemData(
                title: 'Sample T-Shirt',
                quantity: 1,
                unitPrice: Money::from('1299.90', 'TRY'),
                variant: 'Black / XL',
                imageUrl: 'https://example.com/products/sample-tshirt.jpg'
            ),
            new CartItemData(
                title: 'Sample Hoodie',
                quantity: 1,
                unitPrice: Money::from('1199.90', 'TRY'),
                variant: 'Gray / L',
                imageUrl: 'https://example.com/products/sample-hoodie.jpg'
            ),
        ],
        defaultImageUrl: 'https://example.com/assets/default-product.jpg'
    )
);

Paket, Shopier ürün ID’sini ve ödeme yönlendirme URL’sini döndürür. Local veritabanınıza otomatik yazmaz; her projenin sipariş şeması farklı olduğu için bu adımı kendi uygulamanızda yönetirsiniz.

Webhook ve Ödeme Doğrulama

Paket, gelen webhook verisini doğrulayarak güvenli bir sonuç nesnesi üretir.

<?php

require __DIR__ . '/vendor/autoload.php';

use Mebularts\Shopier\Shopier;

$shopier = Shopier::fromEnv();

$result = $shopier->webhooks()->receive(
    rawBody: file_get_contents('php://input') ?: '',
    headers: function_exists('getallheaders') ? getallheaders() : [],
);

if (! $result->isVerified()) {
    // Bildirim alındı fakat güvenli olarak doğrulanamadı.
    // Local siparişi paid yapmayın.
    http_response_code(200);
    exit;
}

if ($result->isPaid()) {
    $shopierOrder = $result->order();

    // 1. product ID / reference / amount / currency eşleşmesini kontrol edin.
    // 2. Kendi merkezi paid handler’ınızı çağırın.
    // 3. Bu handler içinde stok, sepet, e-posta ve kargo adımlarını bir kez çalıştırın.
}

http_response_code(200);

Doğrulama Modları

Mod	Davranış
`auto`	Signature mevcut ve doğrulanabiliyorsa signature ile; aksi durumda Shopier API üzerinden yeniden kontrol ile doğrular.
`api_recheck`	Webhook verisini tek başına ödeme kanıtı saymaz; PAT ile Shopier API’den sipariş detayını yeniden doğrular.
`signature`	Yalnızca signature doğrulaması kullanır. Secret veya uygun signature bilgisi yoksa güvenli biçimde başarısız döner.

Signature doğrulamasını etkinleştirmek için:

$shopier = Shopier::configure(
    ShopierConfig::fromArray([
        'access_token' => $_ENV['SHOPIER_PAT'],
        'webhook_secret' => $_ENV['SHOPIER_WEBHOOK_SECRET'],
        'webhook_signature_encoding' => 'hex',
        'webhook_validation_mode' => 'signature',
    ])
);

Return URL Nasıl Kullanılmalı?

Ödeme sonrası kullanıcı sitenize geri döndüğünde return endpoint’iniz siparişi doğrudan paid yapmamalıdır.

Önerilen yaklaşım:

Payment session paid ise kullanıcıya başarı mesajı gösterin.
Session hâlâ pending veya awaiting_shopier_payment ise “Ödemeniz doğrulanıyor” mesajı gösterin.
Asıl ödeme onayını webhook veya API recheck sonucu verin.
Belirsiz eşleşmeleri manual_review durumunda tutun.

Tam akış örnekleri için examples/README.md dosyasına bakın.

Mevcut E-Ticaret Projelerine Entegrasyon

Paket aşağıdaki işlemleri kendiliğinden yapmaz:

Local sipariş tablosuna kayıt eklemek
Stok düşmek veya stok iadesi yapmak
Sepeti temizlemek
E-posta göndermek
Kargo veya ERP sistemini tetiklemek
Local siparişi doğrudan paid yapmak

Bu yapı bilinçlidir. Her e-ticaret projesinin veritabanı, sipariş kodu, stok ve kargo mimarisi farklıdır.

Tipik uygulama akışı:

Kendi sisteminizde pending local sipariş oluşturun.
Sepet verisiyle dinamik Shopier ürünü oluşturun.
Product ID, redirect URL, beklenen tutar ve currency bilgisini kendi payment session kaydınıza yazın.
Kullanıcıyı Shopier ödeme sayfasına yönlendirin.
Webhook/API recheck sonucunda payment, amount, currency ve ürün/referans eşleşmesini doğrulayın.
Sadece doğrulama başarılıysa merkezi local paid handler’ınızı çağırın.
Stok, sepet, e-posta ve kargo işlemlerini bu handler içinde idempotent biçimde yönetin.

Hata Yönetimi

SDK, hata durumlarını anlamlı exception türleriyle döndürür.

use Mebularts\Shopier\Exception\ShopierException;

try {
    $balance = $shopier->balance()->get();
} catch (ShopierException $exception) {
    // Kullanıcıya token, raw API response veya teknik detay göstermeyin.
    // Kendi logger yapınızla güvenli biçimde kayıt altına alın.
}

Ödeme sayfası oluşturulamadığında kullanıcıya güvenli bir mesaj gösterin:

Shopier ödeme seçeneği şu anda kullanılamıyor. Lütfen başka bir ödeme yöntemi deneyin.

CLI Kullanımı

vendor/bin/shopier health
vendor/bin/shopier balance
vendor/bin/shopier orders:list --limit=10
vendor/bin/shopier webhooks:list
vendor/bin/shopier webhook:verify --file=payload.txt --signature=...

CLI varsayılan olarak token, secret, e-posta, telefon ve benzeri hassas alanları göstermemelidir.

Güvenlik

Token, PAT, webhook secret ve private key değerlerini repository’ye eklemeyin.
Return URL veya gelen webhook isteğini tek başına ödeme başarısı kabul etmeyin.
Local siparişi paid yapmadan önce payment status, amount, currency ve ürün/referans eşleşmesini doğrulayın.
Aynı ödeme bildiriminin stok, e-posta veya kargo işlemlerini ikinci kez başlatmasını engelleyin.
Public issue’lara canlı ödeme verisi, müşteri bilgisi veya secret eklemeyin.
Production ortamında HTTPS kullanın.

Güvenlik açığı bildirimi için SECURITY.md dosyasını inceleyin.

Kalite Kontrolü

composer validate --strict
composer dump-autoload --optimize
composer audit
composer lint
composer analyse
composer test
composer qa

Katkı göndermeden önce en az şu kontrollerin çalışması beklenir:

composer validate --strict
composer qa

Katkı kuralları için CONTRIBUTING.md dosyasına bakın.

Ücretli Kurulum ve Entegrasyon Desteği

Bu paket ücretsiz ve açık kaynak olarak sunulmaktadır.

Mevcut PHP e-ticaret scriptinize Shopier entegrasyonu, legacy geçişi, dinamik checkout akışı, webhook kurulumu, sipariş eşleştirme veya özel ödeme akışı için ücretli kurulum ve teknik destek alabilirsiniz.

Lisans

Bu proje MIT License ile yayınlanmaktadır.

Developed and maintained by Mebularts.

Website · Telegram · WhatsApp · GitHub

mebularts/shopier

包简介

关键字：

README 文档