সাইটস API (Sites API)

সাইটস API (Sites API) হলো playground.wordpress.net কর্তৃক উন্মুক্ত একটি JavaScript API। এটি ডক (Dock)-এর Playgrounds প্যানে প্রদর্শিত ওয়ার্ডপ্রেস সাইটগুলো পরিচালনা করে: সাম্প্রতিক অটোসেভ (autosave), ব্রাউজারে স্থায়ীভাবে সংরক্ষিত প্লেগ্রাউন্ড, লোকাল ডিরেক্টরি প্লেগ্রাউন্ড এবং অস্থায়ী প্লেগ্রাউন্ড।

এই API-টি গ্লোবাল window.playgroundSites-এর মাধ্যমে ব্যবহার করা যায়। পেজ লোডের প্রথম মুহূর্তগুলোতে window.playgroundSites অ্যাসাইন করা থাকে না। এটি উপস্থিত হওয়া পর্যন্ত অপেক্ষা করুন, তারপর সক্রিয় প্লেগ্রাউন্ড ক্লায়েন্টের প্রয়োজন এমন API কল করার আগে isReady() কল করুন।

সাইটস API প্লেগ্রাউন্ড ওয়েবসাইট অ্যাপ্লিকেশনের সাথে আসে, @wp-playground/client লাইব্রেরির সাথে নয়। এটি শীর্ষ-স্তরের পৃষ্ঠায় (/) উন্মুক্ত থাকে, /remote.html-এ নয়। আপনি যদি startPlaygroundWeb-এর মাধ্যমে প্লেগ্রাউন্ড আপনার নিজস্ব পেজে এম্বেড করেন, তবে আপনার আইফ্রেম (iframe) প্যারেন্ট পেজে window.playgroundSites প্রকাশ করবে না — সরাসরি নিয়ন্ত্রণের জন্য এর পরিবর্তে JavaScript API ব্যবহার করুন।

দ্রুত শুরু (Quick start)

playground.wordpress.net খুলুন, ওয়ার্ডপ্রেস লোড হওয়া পর্যন্ত অপেক্ষা করুন, তারপর DevTools-এ এটি চালান:

await playgroundSites.isReady();

playgroundSites.list();
// → [{ slug: 'calm-sunny-park', name: 'Calm Sunny Park', storage: 'opfs', persistence: 'autosave', isActive: true }]

await playgroundSites.keep(undefined, 'My demo site');
// The active autosave is now a permanently saved browser Playground.

const client = playgroundSites.getClient();
await client.listFiles('/wordpress');

ব্রাউজার স্টোরেজ এবং সেভিং উপলভ্য থাকলে একটি নতুন ভিজিট সাধারণত একটি অটোসেভ করা ব্রাউজার প্লেগ্রাউন্ড তৈরি করে। পেজ রিফ্রেশ বা ট্যাব বন্ধ করার সাথে সাথে অপসারিত হবে এমন একটি প্লেগ্রাউন্ডের প্রয়োজন হলে ?storage=temp অথবা createNewTemporarySite() ব্যবহার করুন।

স্টোরেজ এবং পারসিস্টেন্স (Storage and persistence)

প্রতিটি সাইটের একটি স্টোরেজ ব্যাকএন্ড থাকে। সংরক্ষিত সাইটগুলোর একটি পারসিস্টেন্স লাইফসাইকেলও থাকে।

ক্ষেত্র (Field)	মান (Value)	অর্থ (Meaning)
storage	temporary	শুধুমাত্র মেমরিতে সংরক্ষিত (In-memory only)। ব্রাউজার রিফ্রেশ বা ট্যাব বন্ধ করলে এটি অপসারিত হয়।
storage	opfs	ব্রাউজারের Origin Private File System-এ সংরক্ষিত।
storage	local-fs	File System Access API-এর মাধ্যমে একটি লোকাল ডিরেক্টরিতে সংরক্ষিত।
persistence	autosave	একটি সংরক্ষিত রিকভারি পয়েন্ট। প্লেগ্রাউন্ড সাম্প্রতিক পাঁচটি অটোসেভ সংরক্ষণ করে রাখে।
persistence	explicit	একটি স্থায়ীভাবে সংরক্ষিত প্লেগ্রাউন্ড যা ব্যবহারকারী বা API মুছে না ফেলা পর্যন্ত থাকে।

অস্থায়ী প্লেগ্রাউন্ডসমূহ persistence রিপোর্ট করে না কারণ সেখানে সংরক্ষণ করার মতো কোনো স্টোরেজ লাইফসাইকেল নেই।

সাইট তৈরি এবং পরিবর্তন করা (Creating and switching sites)

createNewTemporarySite(slug?, settings?)

একটি নতুন অস্থায়ী সাইট তৈরি করে এবং সেটিতে স্যুইচ করে। সাইটটি বুট সম্পন্ন হলে নতুন সাইটের স্লাগ (slug) প্রদান করে সমাধান (resolve) হয়।

createNewTemporarySite(
	slug?: string,
	settings?: {
		phpVersion?: string; // e.g. '8.4'
		wpVersion?: string; // e.g. '6.8', 'latest', 'nightly', 'beta'
		networking?: boolean;
		language?: string; // e.g. 'pl_PL'
		multisite?: boolean;
	}
): Promise<string>;

প্রতিটি সেটিং একই নামের একটি সমতুল্য Query API প্যারামিটারের সাথে সম্পর্কিত, যেখানে phpVersion মানচিত্রিত (mapped) হয় php-এর সাথে এবং wpVersion মানচিত্রিত হয় wp-এর সাথে। plugin, theme, বা blueprint-url-এর মতো অন্যান্য Query API অপশন এখানে গৃহীত হয় না।

createNewSavedSite(slug?, settings?, options?)

ব্রাউজারে সংরক্ষিত একটি নতুন সাইট তৈরি করে এবং সেটিতে স্যুইচ করে। options.persistence যদি autosave না হয়, তবে সাইটটি একটি স্পষ্ট সংরক্ষণ (explicit save) হিসেবে শুরু হয়।

createNewSavedSite(
	slug?: string,
	settings?: {
		phpVersion?: string;
		wpVersion?: string;
		networking?: boolean;
		language?: string;
		multisite?: boolean;
	},
	options?: {
		persistence?: 'autosave' | 'explicit';
		updateUrl?: boolean;
		excludeFromPruning?: string[];
	}
): Promise<string>;

এই পদ্ধতির মাধ্যমে তৈরি করা অটোসেভ সাইটগুলো UI দ্বারা তৈরি অটোসেভের মতো একই সাম্প্রতিক-পাঁচটি অটোসেভ ছাঁটাই (pruning) প্রক্রিয়ায় অংশ নেয়।

setActiveSite(slug, options?)

একটি ভিন্ন সাইটে স্যুইচ করে এবং এটি বুট করে। সাইটটি প্রস্তুত হলে সমাধান (resolve) হয় অথবা বুট করতে ব্যর্থ হলে প্রত্যাখ্যান (reject) করে। সাইটটি ইতিমধ্যে সক্রিয় থাকলে সাথে সাথেই সম্পন্ন হয়।

setActiveSite(
	siteSlug: string,
	options?: { updateUrl?: boolean }
): Promise<void>;

সাইটের অবস্থা পড়া (Reading site state)

list()

সক্রিয় সাইট সহ প্রতিটি পরিচিত সাইট রিটার্ন করে।

list(): Array<{
	slug: string;
	name: string;
	storage: 'temporary' | 'opfs' | 'local-fs';
	persistence?: 'autosave' | 'explicit';
	isActive: boolean;
}>;

getClient()

সক্রিয় সাইটের জন্য PlaygroundClient রিটার্ন করে, অথবা সাইটটি বিদ্যমান কিন্তু এখনও বুট হওয়া শেষ না হলে undefined রিটার্ন করে। কোনো সাইট একেবারেই নির্বাচিত না থাকলে এটি এরর থ্রো করে, যা সাধারণত পেজ লোডের একেবারে প্রাথমিক পর্যায়ে ঘটে।

getClient(): PlaygroundClient | undefined;

isReady()

সক্রিয় সাইটটি সম্পূর্ণরূপে বুট সম্পন্ন হলে এবং এর PlaygroundClient API কলের জন্য প্রস্তুত হলে এটি সমাধান (resolve) হয়। সাইটটি বুট করতে ব্যর্থ হলে প্রত্যাখ্যান (reject) করে।

পেজ লোড শেষ হওয়ার আগে চালিত স্ক্রিপ্টগুলোর ক্ষেত্রে, প্রথমে window.playgroundSites উপস্থিত হওয়ার জন্য অপেক্ষা করুন:

await new Promise((resolve) => {
	const id = setInterval(() => {
		if (window.playgroundSites) {
			clearInterval(id);
			resolve();
		}
	}, 50);
});
await window.playgroundSites.isReady();

isReady(): Promise<void>;

সাইট স্থায়ী করা এবং সংরক্ষণ করা (Persisting and keeping sites)

অন্যভাবে উল্লেখ না থাকলে এই মেথডগুলো ইতিমধ্যে সংরক্ষিত সাইটগুলোতে কল করা সম্পূর্ণ নিরাপদ।

autosaveTemporarySite(slug?, options?)

একটি অস্থায়ী প্লেগ্রাউন্ডকে অটোসেভ হিসেবে ব্রাউজার স্টোরেজে সংরক্ষণ করে। এটি সাইটের স্লাগ এবং স্টোরেজ ব্যাকএন্ড প্রদান করে। সাইটটি ইতিমধ্যে সংরক্ষিত থাকলে ফাইল অনুলিপি (copy) না করেই বর্তমান স্টোরেজ প্রদান করে।

autosaveTemporarySite(
	slug?: string,
	options?: {
		updateUrl?: boolean;
		excludeFromPruning?: string[];
	}
): Promise<{ slug: string; storage: 'opfs' | 'local-fs' }>;

keep(slug?, name?)

একটি অটোসেভ করা প্লেগ্রাউন্ডকে একটি স্পষ্ট সংরক্ষিত (explicit saved) প্লেগ্রাউন্ড হিসেবে চিহ্নিত করে। এটি শুধুমাত্র লাইফসাইকেল মেটাডেটা পরিবর্তন করে। এটি কোনো ফাইল অনুলিপি করে না, স্টোরেজ ব্যাকএন্ড পরিবর্তন করে না কিংবা সাইটকে রিবুট করে না।

keep(slug?: string, name?: string): Promise<void>;

saveInBrowser(name?)

সক্রিয় অস্থায়ী সাইটটিকে OPFS-এ সংরক্ষণ করে। অটোসেভ করা কোনো সাইটে এটি কল করা হলে, এটি সেই সাইটটিকে একটি স্পষ্ট সংরক্ষিত প্লেগ্রাউন্ড হিসেবে রেখে দেয়।

saveInBrowser(
	name?: string
): Promise<{ slug: string; storage: 'opfs' | 'local-fs' }>;

saveToLocalFileSystem(name?, localFsHandle?)

সক্রিয় অস্থায়ী বা অটোসেভ করা সাইটটিকে একটি লোকাল ডিরেক্টরিতে সংরক্ষণ করে। localFsHandle উল্লেখ না থাকলে ব্যবহারকারীকে একটি ডিরেক্টরি বেছে নেওয়ার প্রম্পট দেখায়। এর জন্য File System Access API প্রয়োজন, তাই এর প্রাপ্যতা ব্রাউজার এবং প্ল্যাটফর্মের ওপর নির্ভর করে।

saveToLocalFileSystem(
	name?: string,
	localFsHandle?: FileSystemDirectoryHandle
): Promise<{ slug: string; storage: 'opfs' | 'local-fs' }>;

সংরক্ষিত সাইট সংশোধন করা (Modifying a stored site)

কোনো অস্থায়ী সাইটে কল করা হলে এই মেথডগুলো এরর থ্রো করে।

rename(newName, slug?)

সক্রিয় সাইট, অথবা slug দ্বারা নির্দিষ্ট সাইটের নাম পরিবর্তন করে।

rename(newName: string, slug?: string): Promise<void>;

setPhpVersion(version)

সক্রিয় সংরক্ষিত সাইটের PHP সংস্করণ পরিবর্তন করে এবং সাইটটিকে রিবুট করে। একটি নতুন সাইটের জন্য PHP সংস্করণ বেছে নিতে, এর পরিবর্তে createNewTemporarySite() বা createNewSavedSite()-এ phpVersion পাস করুন।

setPhpVersion(version: string): Promise<void>;

version প্যারামিটারটি AllPHPVersion ইউনিয়ন থেকে যেকোনো মান গ্রহণ করে। নতুন PHP সংস্করণ প্রকাশের সাথে সাথে সমর্থিত তালিকা পরিবর্তিত হয় — বর্তমান তালিকার জন্য সংযুক্ত সোর্স কোডটি দেখুন।

setNetworking(enabled)

সক্রিয় সংরক্ষিত সাইটের জন্য আউটবাউন্ড (আউটগোয়িং) নেটওয়ার্ক অ্যাক্সেস সক্রিয় বা নিষ্ক্রিয় করে এবং সাইটটিকে রিবুট করে।

setNetworking(enabled: boolean): Promise<void>;

updateRuntimeSettings(settings)

বিদ্যমান সংরক্ষিত প্লেগ্রাউন্ডে পরিবর্তনযোগ্য রানটাইম সেটিংস প্রয়োগ করে: PHP সংস্করণ এবং নেটওয়ার্কিং। সেটিংস ইতিমধ্যে মিলে গেলে, প্লেগ্রাউন্ড বর্তমান ওয়ার্ডপ্রেস পেজটি রিলোড করে।

updateRuntimeSettings(settings: {
	phpVersion: string;
	networking: boolean;
}): Promise<void>;

ওয়ার্ডপ্রেস সংস্করণ, ভাষা এবং মাল্টিসাইট হলো ইনস্টলেশন সেটিংস। এগুলো পরিবর্তনের প্রয়োজন হলে একটি নতুন প্লেগ্রাউন্ড তৈরি করুন।

delete(slug)

একটি সংরক্ষিত সাইট এবং এর স্থায়ী ডেটা মুছে ফেলে। সাইটটি বিদ্যমান না থাকলে বা অস্থায়ী হলে এরর থ্রো করে।

delete(siteSlug: string): Promise<void>;

পরবর্তী পদক্ষেপ (Next steps)

• JavaScript API — getClient() কর্তৃক প্রদত্ত PlaygroundClient-এর সম্পূর্ণ রেফারেন্স
• Query API — নতুন সাইটের সেটিংস প্রতিফলিতকারী URL প্যারামিটারসমূহ
• Blueprints — বর্ণনামূলক সাইট সেটআপ যা সাইট তৈরির সময় কার্যকর হয়