Storyblok Yönetim API’sini PHP ile Otomatikleştirme: Pratik Bir Rehber
Günümüzün hızla değişen dijital dünyasında, içerik yönetimi süreçleri işletmeler için kritik bir öneme sahiptir. Manuel olarak içerik oluşturma, güncelleme ve silme işlemleri, özellikle büyük ölçekli projelerde zaman alıcı, hataya açık ve verimsiz olabilir. Peki, bu süreci nasıl daha akıllı, daha hızlı ve daha güvenilir hale getirebiliriz? İşte tam bu noktada, Storyblok’un güçlü Yönetim API’si (Management API) devreye giriyor ve PHP ile birleştiğinde, içerik otomasyonu için sınırsız olanaklar sunuyor. Bu rehber, Storyblok’taki içerik akışlarınızı PHP kullanarak programatik olarak nasıl yöneteceğinizi adım adım açıklayacak, böylece geliştirme süreçlerinizi optimize ederken içerik stratejinizi güçlendirebileceksiniz.
Storyblok ve Yönetim API’si Nedir? Neden İş Akışlarınız İçin Kritik Öneme Sahiptir?
Storyblok, içerik oluşturuculara sezgisel bir görsel düzenleyici sunarken, geliştiricilere esnek ve API odaklı bir yapı sağlayan modern bir başsız içerik yönetim sistemi (Headless CMS) olarak öne çıkmaktadır. Geleneksel CMS’lerin aksine, Storyblok içeriği sunum katmanından ayırarak, aynı içeriğin web siteleri, mobil uygulamalar, IoT cihazları ve diğer dijital platformlar arasında kolayca dağıtılmasına olanak tanır. Bu mimari, geliştiricilere istedikleri teknolojiyi (örneğin, React, Vue, Angular, Next.js veya PHP tabanlı framework’ler) kullanarak içeriklerini tüketme özgürlüğü verir.
Storyblok’un gücünün önemli bir kısmı, içeriklerinizi programatik olarak yönetmenizi sağlayan iki ana API setinden gelir: İçerik Teslim API’si (Content Delivery API) ve Yönetim API’si (Management API). İçerik Teslim API’si, canlı içerikleri okumak ve web sitenizde veya uygulamanızda göstermek için kullanılırken, Yönetim API’si Storyblok’un içerik yönetim paneline erişmenizi ve içerikleri oluşturma, güncelleme, silme, varlıkları yönetme, kullanıcıları ve alanları yapılandırma gibi tüm yönetimsel işlemleri otomatikleştirmenizi sağlar.
Yönetim API’si, özellikle aşağıdaki senaryolarda iş akışlarınız için kritik öneme sahiptir:
* Veri Göçü (Data Migration): Eski bir CMS’ten veya başka bir kaynaktan Storyblok’a binlerce içerik veya varlık taşırken, manuel giriş yapmak yerine Yönetim API’si ile bu süreci tamamen otomatikleştirebilirsiniz. Bu, hem zaman hem de insan hatası riskini minimize eder.
* Toplu İçerik Güncellemeleri: Belirli bir kategoriye ait tüm ürünlerin fiyatlarını güncellemek, belirli bir etikete sahip tüm blog yazılarına yeni bir yazar eklemek veya kampanyalı ürünlerin açıklamasını değiştirmek gibi toplu işlemler, Yönetim API’si ile saniyeler içinde gerçekleştirilebilir.
* CI/CD Entegrasyonu: Sürekli Entegrasyon/Sürekli Dağıtım (CI/CD) süreçlerinizin bir parçası olarak, yeni bir kod dağıtımıyla birlikte Storyblok’ta otomatik olarak test içerikleri oluşturabilir, mevcut içerikleri güncelleyebilir veya önbelleği temizleyebilirsiniz. Bu, geliştirme ve yayınlama süreçlerini hızlandırır.
* Uygulama Entegrasyonları: E-ticaret sistemleri, CRM’ler veya diğer üçüncü taraf uygulamalarınızdan gelen verileri Storyblok’a otomatik olarak senkronize edebilirsiniz. Örneğin, yeni bir ürün e-ticaret sitenizde yayınlandığında, Storyblok’ta otomatik olarak bir ürün hikayesi (story) oluşturulabilir.
* Çok Dilli İçerik Yönetimi: Farklı dillerdeki içeriklerin oluşturulması ve senkronize edilmesi, özellikle büyük projelerde karmaşık olabilir. Yönetim API’si sayesinde, ana dildeki bir içeriğin diğer dillere otomatik olarak kopyalanmasını veya çeviri hizmetleriyle entegrasyonunu sağlayabilirsiniz.
Özetle, Yönetim API’si, Storyblok’u sadece bir içerik deposu olmaktan çıkarıp, dinamik ve entegre bir içerik platformuna dönüştüren güçlü bir araçtır. PHP gibi yaygın ve güçlü bir sunucu tarafı diliyle birleştiğinde, geliştiricilere içerik yönetim süreçlerinde eşsiz bir esneklik ve otomasyon yeteneği sunar. Bu sayede, geliştiriciler daha az tekrar eden görevlerle uğraşırken, içerik yöneticileri daha hızlı ve tutarlı içerik dağıtımının keyfini çıkarabilirler.
PHP ile Storyblok Yönetim API’sine İlk Adım: Kimlik Doğrulama ve Kurulum Süreci Nasıl İşler?
Storyblok Yönetim API’sini PHP ile kullanmaya başlamadan önce, gerekli kurulumları yapmalı ve API’ye erişim için kimlik doğrulamayı (authentication) sağlamalısınız. Bu bölüm, projenizi nasıl hazırlayacağınızı ve Storyblok ile güvenli bir bağlantı kurmanın temel adımlarını açıklayacaktır.
Öncelikle, bir PHP projesine ihtiyacınız olacak. Eğer halihazırda bir projeniz yoksa, basit bir dizin oluşturarak başlayabilirsiniz. PHP’nin kurulu olduğundan ve Composer (PHP bağımlılık yöneticisi) erişiminizin olduğundan emin olun. Composer, HTTP istekleri yapmak için kullanacağımız Guzzle gibi kütüphaneleri kolayca kurmamızı sağlayacaktır.
# Yeni bir proje dizini oluşturun ve içine girin
mkdir storyblok-otomasyon
cd storyblok-otomasyon
# Composer'ı kullanarak Guzzle HTTP istemcisini kurun
composer require guzzlehttp/guzzle
Guzzle, PHP uygulamalarınızda HTTP istekleri göndermek için popüler ve kullanımı kolay bir kütüphanedir. Storyblok Yönetim API'si de HTTP tabanlı RESTful bir API olduğu için Guzzle bizim için ideal bir seçim olacaktır.
API Token'ınızı Alma:
Storyblok Yönetim API'sine erişmek için bir Yönetim API Token'ına ihtiyacınız var. Bu token, API isteklerinizin kimliğini doğrular ve hangi izinlere sahip olduğunuzu belirler. Token'ı almak için şu adımları izleyin:
1. Storyblok hesabınıza giriş yapın.
2. İlgili alan (Space) ayarları sayfasına gidin.
3. Sol menüden "Settings" (Ayarlar) ve ardından "API Keys" (API Anahtarları) seçeneğine tıklayın.
4. Burada "Management API Token" bölümünü bulacaksınız. Bu token'ı kopyalayın.
* Önemli Not: Yönetim API Token'ları oldukça güçlüdür ve alanınızdaki tüm içerik üzerinde okuma, yazma, silme gibi işlemleri yapabilir. Bu nedenle, bu token'ı asla genel depolarda (örneğin GitHub) paylaşmamalı ve üretim ortamında güvenli bir şekilde (örneğin ortam değişkenleri olarak) saklamalısınız.
Temel Bir PHP İstemcisi Oluşturma:
Token'ınızı aldıktan sonra, API istekleri göndermek için basit bir PHP betiği oluşturabiliriz. index.php adında bir dosya oluşturalım:
'https://api.storyblok.com/v1/',
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => $managementApiToken, // Token'ı Authorization başlığına ekliyoruz
],
]);
try {
// Örnek bir istek: Alanınızdaki tüm hikayeleri listeleme
// Bu sadece bir örnek, Management API'sinde stories endpoint'i space_id ile daha farklı çalışır.
// İlk adım olarak, space detaylarını almayı deneyelim.
$response = $client->get("spaces/{$spaceId}");
$statusCode = $response->getStatusCode();
$body = json_decode($response->getBody()->getContents(), true);
echo "Durum Kodu: " . $statusCode . "\n";
echo "Alan Detayları:\n";
print_r($body);
} catch (RequestException $e) {
echo "Hata Oluştu: " . $e->getMessage() . "\n";
if ($e->hasResponse()) {
echo "Yanıt: " . $e->getResponse()->getBody()->getContents() . "\n";
}
}
?>
Yukarıdaki kod bloğunda, getenv() fonksiyonunu kullanarak API token'ınızı ve alan ID'nizi ortam değişkenlerinden almaya çalıştık. Bu, token'ı doğrudan kod içine yazmaktan daha güvenli bir yöntemdir. Projenizin kök dizininde bir .env dosyası oluşturarak bu değişkenleri tanımlayabilirsiniz (örneğin, STORYBLOK_MANAGEMENT_API_TOKEN=sb_your_token_here ve STORYBLOK_SPACE_ID=123456). Ardından, phpdotenv gibi bir kütüphane kullanarak bu değişkenleri PHP'ye yükleyebilirsiniz: composer require vlucas/phpdotenv.
Bu ilk adımda, Guzzle istemcisini yapılandırdık ve Authorization başlığına API token'ımızı ekledik. Ardından, alanınızın (space) detaylarını almak için basit bir GET isteği gönderdik. Bu başarılı bir şekilde çalıştığında, Storyblok Yönetim API'si ile iletişim kurmaya hazırsınız demektir. Artık içerik oluşturma, güncelleme ve silme gibi daha karmaşık işlemlere geçebiliriz. Bu temel yapı, ileride yapacağımız tüm API çağrıları için başlangıç noktamız olacaktır.
Storyblok Kaynaklarını Yönetme: Hikayeler (Stories) ve Bileşenler (Components) Nasıl Oluşturulur ve Güncellenir?
Storyblok'un temel yapı taşları hikayeler (stories) ve bileşenlerdir (components). Hikayeler, web sitenizdeki sayfaları, blog yazılarını veya ürün detaylarını temsil ederken, bileşenler bu hikayelerin içeriğini oluşturan modüler parçalardır (başlıklar, metin blokları, resimler, kartlar vb.). Yönetim API'si sayesinde, bu yapıları PHP ile programatik olarak oluşturabilir, güncelleyebilir ve silebilirsiniz.
Hikaye (Story) Oluşturma:
Yeni bir hikaye oluşturmak için, Storyblok Yönetim API'sinin spaces/{space_id}/stories endpoint'ine bir POST isteği göndermeniz gerekir. İstek gövdesinde (request body), hikayenin adını, slug'ını (URL dostu adı), bileşen yapısını ve gerekirse üst hikaye (parent story) ID'sini belirtmelisiniz.
Örneğin, yeni bir blog yazısı oluşturmak istediğimizi varsayalım. Blog yazımız bir "page" (sayfa) bileşen türünde olacak ve içinde bir "hero" (kahraman bölümü) ve "richtext" (zengin metin) bileşenleri bulunacak.
load();
$managementApiToken = getenv('STORYBLOK_MANAGEMENT_API_TOKEN');
$spaceId = getenv('STORYBLOK_SPACE_ID');
if (empty($managementApiToken) || empty($spaceId)) {
die("Hata: Yönetim API Token'ı veya Alan ID'si tanımlanmadı.");
}
$client = new Client([
'base_uri' => 'https://api.storyblok.com/v1/',
'headers' => [
'Content-Type' => 'application/json',
'Authorization' => $managementApiToken,
],
]);
try {
$storyData = [
'story' => [
'name' => 'PHP ile Yeni Blog Yazısı',
'slug' => 'php-ile-yeni-blog-yazisi-' . uniqid(), // Benzersiz bir slug oluştur
'parent_id' => null, // Kök dizinde oluşturmak için null
'content' => [
'component' => 'page', // Ana bileşen türü
'_uid' => uniqid(),
'title' => 'PHP ile Otomatik İçerik Oluşturma',
'body' => [
[
'component' => 'hero',
'_uid' => uniqid(),
'headline' => 'Storyblok ve PHP Gücü',
'image' => 'https://a.storyblok.com/f/123456/1200x800/some_image.jpg', // Örnek resim URL'si
'call_to_action_text' => 'Daha Fazla Oku',
'call_to_action_link' => '/blog/detaylar'
],
[
'component' => 'richtext',
'_uid' => uniqid(),
'text' => [
'type' => 'doc',
'content' => [
[
'type' => 'paragraph',
'content' => [
['type' => 'text', 'text' => 'Bu blog yazısı, Storyblok Yönetim API\'si ve PHP kullanılarak otomatik olarak oluşturulmuştur. Bu yöntemle içerik yönetim süreçlerinizi büyük ölçüde hızlandırabilirsiniz.'],
],
],
[
'type' => 'paragraph',
'content' => [
['type' => 'text', 'text' => 'Otomasyon sayesinde, manuel hataları azaltırken tutarlılığı artırabilirsiniz.'],
],
],
],
],
],
],
'seo_title' => 'PHP Storyblok Otomasyonu',
'seo_description' => 'PHP ile Storyblok içeriklerini otomatik oluşturma rehberi.',
],
'is_startpage' => false,
'published' => true, // Oluştururken yayınlamak için true yapın
],
];
$response = $client->post("spaces/{$spaceId}/stories", [
'json' => $storyData,
]);
$statusCode = $response->getStatusCode();
$body = json_decode($response->getBody()->getContents(), true);
echo "Yeni Hikaye Oluşturuldu! Durum Kodu: " . $statusCode . "\n";
echo "Hikaye ID: " . $body['story']['id'] . "\n";
echo "Hikaye URL: " . $body['story']['full_slug'] . "\n";
} catch (RequestException $e) {
echo "Hata Oluştu: " . $e->getMessage() . "\n";
if ($e->hasResponse()) {
echo "Yanıt: " . $e->getResponse()->getBody()->getContents() . "\n";
}
}
?>
Yukarıdaki örnekte, storyData dizisi, oluşturulacak hikayenin tüm özelliklerini ve içindeki bileşenlerin yapısını tanımlar. _uid alanları, Storyblok'un bileşenleri benzersiz bir şekilde tanımlaması için gereklidir ve uniqid() fonksiyonuyla oluşturulabilir. parent_id ile hikayeyi belirli bir klasör altına yerleştirebilirsiniz. published anahtarı, hikayenin hemen yayınlanıp yayınlanmayacağını kontrol eder.
Hikaye (Story) Güncelleme:
Mevcut bir hikayeyi güncellemek için, spaces/{space_id}/stories/{story_id} endpoint'ine bir PUT isteği göndermeniz gerekir. İstek gövdesi, story nesnesini içermeli ve güncellenecek alanları belirtmelidir. Sadece değiştirmek istediğiniz alanları göndermeniz yeterlidir; geri kalan alanlar olduğu gibi kalacaktır.
Örneğin, yukarıda oluşturduğumuz blog yazısının başlığını ve açıklamasını güncellemek isteyelim:
[
'name' => 'PHP ile Otomatik Blog Yazısı (Güncellendi)',
'content' => [
'component' => 'page', // Ana bileşen türü aynı kalmalı
'_uid' => uniqid(), // Yeni bir uid gerekebilir veya mevcut uid korunabilir
'title' => 'PHP ile İçerik Otomasyonu: Gelişmiş Rehber',
'body' => [
// Mevcut bileşenleri burada tekrar tanımlamanız veya
// sadece belirli bir bileşeni güncellemek için GET ile çekip modify etmeniz gerekebilir.
// Bu örnekte sadece başlığı güncelliyoruz.
// Eğer tüm body'yi göndermezseniz mevcut body silinir, dikkat!
// Genellikle önce GET ile hikayeyi çekip, sonra değişiklikleri yapıp PUT ile gönderilir.
[
'component' => 'hero',
'_uid' => uniqid(), // Bu kısmı güncellerken mevcut _uid kullanmalısınız
'headline' => 'Storyblok ve PHP: Yeni Nesil İçerik Yönetimi', // Başlığı güncelledik
'image' => 'https://a.storyblok.com/f/123456/1200x800/some_image_updated.jpg',
'call_to_action_text' => 'Hemen Keşfet',
'call_to_action_link' => '/blog/yeni-detaylar'
],
[
'component' => 'richtext',
'_uid' => uniqid(), // Bu kısmı güncellerken mevcut _uid kullanmalısınız
'text' => [
'type' => 'doc',
'content' => [
[
'type' => 'paragraph',
'content' => [
['type' => 'text', 'text' => 'Bu yazı, PHP ve Storyblok Yönetim API\'sinin güncel yeteneklerini sergilemek üzere güncellenmiştir. İçeriklerinizi dinamik olarak yönetin.'],
],
],
],
],
],
],
'seo_title' => 'PHP Storyblok Gelişmiş Otomasyon',
'seo_description' => 'PHP ile Storyblok içeriklerini otomatik güncelleme ve yönetme rehberi.',
],
'published' => true, // Güncelleme sonrası yayınlamak için true yapın
],
];
$response = $client->put("spaces/{$spaceId}/stories/{$storyIdToUpdate}", [
'json' => $updatedStoryData,
]);
$statusCode = $response->getStatusCode();
$body = json_decode($response->getBody()->getContents(), true);
echo "Hikaye Güncellendi! Durum Kodu: " . $statusCode . "\n";
echo "Güncellenen Hikaye Adı: " . $body['story']['name'] . "\n";
} catch (RequestException $e) {
echo "Hata Oluştu: " . $e->getMessage() . "\n";
if ($e->hasResponse()) {
echo "Yanıt: " . $e->getResponse()->getBody()->getContents() . "\n";
}
}
?>
Güncelleme işleminde dikkat edilmesi gereken en önemli nokta, content alanını gönderirken, hikayenin tüm mevcut içeriğini (bileşenleri dahil) doğru bir şekilde yeniden yapılandırmanız gerektiğidir. Eğer sadece bir bileşeni değiştirmek istiyorsanız, genellikle önce hikayeyi GET isteği ile çekip, content yapısını PHP'de manipüle edip, ardından PUT isteğiyle geri göndermek daha güvenli bir yaklaşımdır. Aksi takdirde, göndermediğiniz bileşenler silinebilir.
Bu örnekler, hikayeleri ve bileşenleri PHP ile nasıl oluşturup güncelleyeceğinize dair temel bir anlayış sunar. Bu yetenekler, otomatik içerik dağıtımı, şablon tabanlı içerik üretimi ve dinamik sayfa oluşturma gibi pek çok otomasyon senaryosunun temelini oluşturur.
Dijital Varlık Yönetimi: Storyblok'a Resim ve Dosya Yükleme Süreci Nasıl İşler?
Modern web siteleri ve uygulamaları, metin içeriğinin yanı sıra resimler, videolar, PDF'ler gibi dijital varlıklara (assets) büyük ölçüde bağımlıdır. Storyblok, bu varlıkları merkezi bir yerde yönetmenize olanak tanır ve Yönetim API'si aracılığıyla bu varlıkları programatik olarak yükleyebilir, güncelleyebilir ve silebilirsiniz. PHP ile Storyblok'a dosya yüklemek, özellikle e-ticaret siteleri için ürün görsellerini veya haber siteleri için makale eklerini otomatik olarak senkronize etme gibi senaryolarda hayati öneme sahiptir.
Storyblok'a dosya yükleme süreci genellikle iki ana adımdan oluşur:
1. Yükleme URL'si Talep Etme: Doğrudan Storyblok API'sine dosya yüklemek yerine, Storyblok size geçici bir yükleme URL'si sağlar. Bu, yükleme işleminin daha güvenli ve verimli olmasını sağlar.
2. Dosyayı Yükleme: Aldığınız geçici URL'ye dosyayı (genellikle bir multipart/form-data isteği ile) yüklersiniz.
Aşağıda, bir resim dosyasını Storyblok'a PHP ile nasıl yükleyeceğinize dair adım adım bir örnek bulunmaktadır:
load();
$managementApiToken = getenv('STORYBLOK_MANAGEMENT_API_TOKEN');
$spaceId = getenv('STORYBLOK_SPACE_ID');
if (empty($managementApiToken) || empty($spaceId)) {
die("Hata: Yönetim API Token'ı veya Alan ID'si tanımlanmadı.");
}
$client = new Client([
'base_uri' => 'https://api.storyblok.com/v1/',
'headers' => [
'Authorization' => $managementApiToken,
],
]);
// Yüklenecek dosyanın yolu (örneğin, projenizin kök dizininde bir 'uploads' klasörü olsun)
$filePath = __DIR__ . '/uploads/sample-image.jpg';
$fileName = basename($filePath);
$fileSize = filesize($filePath);
$mimeType = mime_content_type($filePath);
if (!file_exists($filePath)) {
die("Hata: Dosya bulunamadı: " . $filePath);
}
try {
// Adım 1: Yükleme URL'si talep etme
$uploadRequestPayload = [
'filename' => $fileName,
'size' => $fileSize,
'mime_type' => $mimeType,
];
$response = $client->post("spaces/{$spaceId}/assets", [
'json' => $uploadRequestPayload,
'headers' => [
'Content-Type' => 'application/json', // Bu istek için Content-Type önemli
],
]);
$statusCode = $response->getStatusCode();
$body = json_decode($response->getBody()->getContents(), true);
if ($statusCode !== 200 && $statusCode !== 201) {
throw new \Exception("Yükleme URL'si alma hatası: " . print_r($body, true));
}
$uploadUrl = $body['upload_url'];
$assetId = $body['asset']['id']; // Oluşturulan varlığın ID