ScratchByPHP v0.8.5

Geliştirici Dokümantasyonu

Developer Documentation

ScratchByPHP; PHP siteleri, dashboard'lar, backend servisleri ve CLI/worker uygulamaları için Scratch Project/User/Studio API, authenticated session, Cloud Variables, CloudRequests/RPC, CloudDatabase, Analyzer/SB3, Watcher, reliability araçları ve gömülebilir Wizard Pro sunan PHP-first SDK/toolkit'tir.

ScratchByPHP is a PHP-first SDK/toolkit for websites, dashboards, backend services and CLI/workers: Project/User/Studio APIs, authenticated sessions, Cloud Variables, CloudRequests/RPC, CloudDatabase, Analyzer/SB3, Watcher, reliability tooling and the embeddable Wizard Pro.

PACKAGE

scratchbyphp/scratchbyphp

VERSION

0.8.5

PHP

8.1+

LICENSE

MIT

Release overview

v0.8.5'te öne çıkanlar

Wizard Pro

Draggable/resizable/fullscreen Control Center; public API, auth, Cloud, Watcher, Analyzer ve developer tools.

CloudDB Pro

CloudDatabase key/value → MySQL bridge; JSON config, prepared statement, transaction ve server-side profiles.

Turkish Studio Trending

Türk isimli stüdyoları keşfeder, projeleri tekilleştirir ve custom trend algoritmasıyla ranklar.

Watcher 2.0

Fresh polling, persistent state, queue, jitter/backoff ve proje değişim event'leri.

Reliability / DX

Cache 2.0, Batch 2.0, Retry Policy, Circuit Breaker, Metrics ve Doctor 2.0.

Analyzer / ProjectDiff

Analyzer 2.0, opcode/warnings ve proje karşılaştırma; toArray() + summary().

Kurulum / Installation

Önerilen kurulum Composer'dır.

composer require scratchbyphp/scratchbyphp

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

use ScratchByPHP\Scratch;

$scratch = new Scratch();
$project = $scratch->project(104);

echo $project->title();
echo $project->views();

Extensions: curl, openssl ve json core kullanım için; zip SB3 archive özellikleri, mysqli CloudDB Pro MySQL aktarımı için gerekir.

Wizard Pro / Control Center

v0.8.5 FEATURE

Wizard Pro, ScratchByPHP API yüzeyini siteye gömülen taşınabilir bir modal üzerinden kullanabilmenizi sağlar. Draggable, resizable, fullscreen yapılabilir; sonuç JSON'unu ve yapılan işlemin PHP kodunu yan yana gösterebilir.

Temel entegrasyon

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

use ScratchByPHP\Scratch;

$scratch = new Scratch();

$wizard = $scratch->wizard([
    'allow_auth'   => true,
    'allow_writes' => true
]);

// ÖNEMLİ: HTML çıktısından önce çağır.
$wizard->handle();
?>
<!doctype html>
<html>
<body>
    <h1>Benim sitem</h1>

    <?= $wizard->render([
        'title' => 'ScratchByPHP Control Center',
        'width' => 980,
        'height' => 680
    ]) ?>
</body>
</html>

Public / Discovery

Project, User, Studio, Search/Explore, Turkish Studio Trending, Analyzer ve ProjectDiff.

Authenticated

Scratch login, Project/User/Studio authenticated actions. Password persist edilmez; Scratch session ID browser JSON'una verilmez.

Cloud

Cloud Variables, history, setVerified, CloudDatabase, CloudDB Pro ve CloudRequests handle-once araçları.

Developer

Watcher baseline/tick, Doctor/Health, Metrics, Circuit Breaker ve PHP kod üretici.

Server-side CloudDB Profili

DB credentials'ı modal input'una koymayın. Wizard yalnızca profil adını görsün:

$wizard = $scratch->wizard([
    'clouddb_profiles' => [
        'main' => __DIR__ . '/../secure/mysql.json'
    ]
]);

Browser yalnızca main adını görür; JSON path, database username/password ve diğer server-side bilgiler response'a gönderilmez.

Custom CloudRequests route

$wizard = $scratch->wizard([
    'cloud_request_handlers' => [
        'sum' => fn(array $params) => array_sum($params),
        'hello' => fn(array $params) => 'Merhaba ' . ($params[0] ?? 'Scratch')
    ]
]);

Wizard güvenlik modeli: same-origin POST endpoint, CSRF doğrulaması, server-side PHP session, sensitive response redaction ve destructive işlemler için onay. Authenticated kullanımda HTTPS önerilir.

Architecture

Scratch API / WebSocket

ScratchByPHP v0.8.5

Website / Backend / Worker / CLI

Public API & Discovery

$project = $scratch->project(104);
echo $project->title();
echo $project->author();
echo $project->views();
echo $project->loves();
echo $project->favorites();

$user = $scratch->user('griffpatch');
$projects = $user->projects();

$studio = $scratch->studio(123456);
$projects = $studio->allProjects();

$projectResults = $scratch->searchProjects('platformer');
$studioResults  = $scratch->searchStudios('türk');

Authentication & Session

$session = $scratch->login('KullaniciAdi', 'Sifre');

$project = $session->project(104);
$studio  = $session->studio(123456);
$user    = $session->user('ExampleUser');
$cloud   = $session->cloud(104);

$session = $scratch->loginWithSessionId(
    getenv('SCRATCH_SESSION_ID')
);

Not: password/session ID gibi değerleri repo'ya commit etmeyin. Environment variable veya server-side secret storage kullanın.

Project API

$project = $scratch->project(104);

$data = $project->get();
$fresh = $project->refresh();
$comments = $project->comments(20, 0);
$remixes = $project->remixes(20, 0);

$analysis = $project->analyze();
$summary = $analysis->summary();

Authenticated actions

$project = $session->project(104);
$project->love();
$project->favorite();
$project->postComment('Merhaba Scratch!');
$project->share();

Utilities: Analyzer, SB3 download/archive, Scratch/TurboWarp player URL/helper ve JSON export araçları.

User API

$user = $scratch->user('griffpatch');
$projects  = $user->projects();
$followers = $user->followers();
$following = $user->following();
$favorites = $user->favorites();

$authUser = $session->user('ExampleUser');
$authUser->follow();

Studio API

allProjects() pagination'ı otomatik yöneterek stüdyodaki proje havuzunu toplamak için kullanılır.

$studio = $scratch->studio(123456);

$data = $studio->get();
$projects = $studio->allProjects();
$curators = $studio->curators();
$managers = $studio->managers();

$authStudio = $session->studio(123456);
$authStudio->addProject(104);
$authStudio->inviteCurator('ExampleUser');
$authStudio->promoteCurator('ExampleUser');
$authStudio->setTitle('Yeni başlık');

Turkish Studio Trending

v0.8.5

Türkçe odaklı Scratch proje havuzu oluşturur: türk, Türk, TÜRK studio aramaları → studio ID deduplication → Studio::allProjects() → project deduplication → local ranking.

$projects = $scratch->turkishTrending(
    limit: 20,
    scan: 120
);

// Alias
$projects = $scratch->turkishTrendProjects(20, 120);

Signal	Default weight
Views	35%
Loves	15%
Favorites	10%
Shared-date freshness	40%

Views/loves/favorites aday havuzu içinde log-normalize edilir. Sonuçlar turkish_trend.rank, score, signal breakdown ve source studios bilgisini taşır.

Cloud Variables

$cloud = $session->cloud(104);
$cloud->connect();

$current = $cloud->getRemote('score');
$result  = $cloud->setVerified('score', 500);

$cloud->setMany([
    'score' => 500,
    'level' => 5
]);

$history = $cloud->history('score');
$cloud->disconnect();

Events / listening

$cloud->connect();

$cloud->onVariable('score', function ($value, $variable) {
    echo 'New score: ' . $value;
});

$cloud->listen();

CloudRequests / RPC

$rpc = $cloud->requests('request', 'response');

$rpc->route('sum', function (array $params) {
    return array_sum($params);
});

$rpc->run();

Uzun süre çalışan CloudRequests listener'ları web request yerine CLI/worker ortamında çalıştırmak daha uygundur.

CloudDatabase & CloudDB Pro

MySQL bridge

$db = $cloud->database('db');
$db->set('level', 12);
echo $db->get('level');
$db->increment('coins', 10);
$db->delete('level');

CloudDB Pro → MySQL

$result = $cloud
    ->database('db')
    ->getToDB(__DIR__ . '/mysql.json');

// Alias
$result = $cloud
    ->database('db')
    ->exportToMySQL(__DIR__ . '/mysql.json');

Aktarım prepared statements, transaction ve identifier validation kullanır. Optional upsert ve auto-create desteklenir.

SQL plan / dry preparation

use ScratchByPHP\Cloud\CloudDatabase;

$plan = CloudDatabase::planToDB(
    ['level' => 12, 'coins' => 500],
    [
        'table' => 'scratch_cloud',
        'key_column' => 'cloud_key',
        'value_column' => 'cloud_value'
    ]
);

Watcher 2.0

Watcher webhook değil, polling tabanlıdır. Fresh project state kullanır; normal project cache canlı değişiklikleri gizlemez.

$watch = $scratch
    ->watch()
    ->interval(10)
    ->project(104);

$baseline = $watch->baseline();

$watch->onView(fn($new, $old) => print("$old -> $new"));
$watch->onLove(...);
$watch->onFavorite(...);
$watch->onRemix(...);
$watch->onComment(...);
$watch->onChange(...);

$watch->run();

Persistent state, event queue, jitter ve backoff desteği Watch katmanında bulunur. Comment takibi project stats.comments yerine latest comment ID üzerinden yapılır.

Analyzer 2.0 / ProjectDiff

$analysis = $scratch->project(104)->analyze();

$summary  = $analysis->summary();
$warnings = $analysis->warnings();
$opcodes  = $analysis->opcodeCounts();

Project comparison

$diff = $scratch->compareProjects(104, 105);

$data = $diff->toArray();

// Compatibility alias
$summary = $diff->summary();

Reliability & Developer Experience

Cache 2.0

$scratch->cacheRules([
  'project:' => 30,
  'user:' => 120,
  'studio:' => 60
]);

Retry + Circuit Breaker

$scratch->retry()
  ->maxAttempts(4)
  ->backoff('exponential')
  ->retryOn([429,500,502,503]);

$scratch->circuitBreaker()
  ->threshold(5)
  ->cooldown(30);

Metrics

$metrics = $scratch
    ->metrics()
    ->summary();

Doctor / Health

$health = $scratch
    ->healthCheck(true);

Batch / Parallel

$result = $scratch->batch()
    ->project(104)
    ->project(105)
    ->user('griffpatch')
    ->concurrency(4)
    ->timeout(15)
    ->retries(2)
    ->run();

SB3 Tools / Validator

$validator = new ScratchByPHP\Sb3\Sb3Validator();
$result = $validator->validate('project.sb3');

project.json, asset references, missing/duplicate assets ve çeşitli archive sorunlarını kontrol etmek için kullanılır.

CLI & Testing

php bin/scratchbyphp project 104 --json
php bin/scratchbyphp user griffpatch --json
php bin/scratchbyphp studio 123456 --json
php bin/scratchbyphp doctor --json
php bin/scratchbyphp check-api --json
php bin/scratchbyphp sb3:validate project.sb3 --json

Repo; smoke/security regression testleri, v0.8.x feature matrix, Watcher, Wizard, ProjectDiff ve v0.8.5 feature testlerini içerir. FakeScratch, PHPUnit/PHPStan yapılandırmaları da developer tooling katmanının parçasıdır.

Registration Assistant

Credential helper sağlar; CAPTCHA bypass veya toplu kayıt otomasyonu sağlamaz.

$registration = $scratch->registration();
$result = $registration->generateAvailableCredentials('ScratchUser');

$json = $registration->credentialsJson(
    'ScratchUser_ABC123',
    'StrongPassword123!',
    'mail@example.com'
);

Security

Authenticated host allowlist

Credential-bearing HTTP calls Scratch HTTPS hostlarıyla sınırlandırılır.

Secret redaction

Logger/session/token/password/cookie gibi değerleri maskeler.

Session validation

Session IDs ve compressed payload boyutları doğrulanır/sınırlandırılır.

Wizard CSRF

Wizard API POST istekleri CSRF token ile korunur.

Server-side secrets

Scratch session ID ve CloudDB MySQL profiles browser'a expose edilmez.

MySQL safety

Prepared statement, transaction ve table/column identifier validation.

API Reference — Major Surface

Area	Major methods / concepts
Scratch	login, loginWithSessionId, project, user, studio, searchProjects, searchStudios, exploreProjects, turkishTrending, turkishTrendProjects, batch, parallel, watch, compareProjects, wizard, healthCheck, cacheRules, metrics, retry, circuitBreaker
Project	get, refresh, title, author, views, loves, favorites, comments, remixes, love/unlove, favorite/unfavorite, postComment, share/unshare, analyze, downloadSb3, sb3, player, run
User	get, projects, followers, following, favorites, studios, follow/unfollow, postComment, setBio, setStatus
Studio	get, projects, allProjects, curators, managers, comments, addProject, removeProject, inviteCurator, promoteCurator, removeCurator, follow/unfollow, setTitle, setDescription
Cloud	connect, disconnect, set, getRemote, setVerified, setMany, variables, history, waitUntil, onVariable, listen, requests, database
CloudDatabase	all, get, set, delete, has, increment, decrement, clear, getToDB, exportToMySQL, planToDB
Watcher	project, interval, baseline, snapshot, tick, run, onView, onLove, onFavorite, onRemix, onComment, onChange, persistent state, event queue
Analysis	analyze, summary, warnings, opcodeCounts, compareProjects, ProjectDiff::toArray, ProjectDiff::summary

AI / llms.txt

Machine-readable llms.txt, ChatGPT, Claude, Gemini ve coding agent'ların ScratchByPHP v0.8.5 API'sini doğru anlaması için hazırlanmıştır. Wizard Pro, CloudDB Pro, Watcher 2.0, Turkish Studio Trending, ProjectDiff ve reliability yüzeyini açıklar.

Open llms.txt

AI entegrasyonlarında stable/documented version 0.8.5 kabul edilmelidir. Turkish Studio Trending bir project-description hashtag filtresi değildir; studio discovery + project ranking sistemidir.