Skip to content

Settings, Assets, and Translation ​

Settings ​

Settings are available through ws_setting() without creating or registering an application settings provider. The framework automatically registers WpStarter\Wordpress\Setting\SettingServiceProvider after application providers have been registered, unless a provider extending that class is already present.

Configure settings under settings in the skeleton's config/wordpress.php:

php
<?php
return [
    'settings' => [
        'option_key' => 'ws_settings',
        'autosave' => true,
        'restart_queue' => true,
    ],
];

These are also the framework defaults when the configuration file is absent. The full configuration keys are wordpress.settings.option_key, wordpress.settings.autosave, and wordpress.settings.restart_queue; for example, read the option key with ws_config('wordpress.settings.option_key', 'ws_settings'). Choose an application-specific option_key before storing settings. Changing the key later selects another WordPress option; it does not migrate existing data.

The repository supports dotted keys:

php
$name = ws_setting('sample.name', 'Example');
ws_setting(['sample.name' => 'Updated']);
ws_setting()->set('sample.enabled', true);
ws_setting()->save();

ws_setting($key, $default) reads a value. Passing an array sets values in memory; calling with no arguments returns the repository. It also supports get(), set(), has(), and array access.

With wordpress.settings.autosave enabled, changes are saved at WordPress shutdown if the settings repository has been resolved. Call save() explicitly when persistence must happen before returning, as in the admin form example. Settings are stored together in the configured option; save($autoload = false) calls update_option().

With wordpress.settings.restart_queue enabled, the provider listens for updates to that option, reloads the repository, and calls queue:restart. Set either configuration flag to false to disable its behavior. Queue workers retain their own in-memory state, so a restart is useful when settings change.

Remove settings with forget(). Deletions mark the repository as changed and are persisted by save() or the automatic shutdown save:

php
ws_setting()->forget('sample.name', 'sample.enabled');
ws_setting()->save();

unset($settings->key) and unset($settings['key']) also remove keys. Setting a key to null removes it; the repository does not retain a stored null value. reload() reads the option again and discards pending in-memory changes.

Use ws_config() for deployment configuration and ws_setting() for editable WordPress options. The repository is not a WordPress Settings API form registration system.

Frontend and admin assets ​

For build tools and Blade asset tags, see Vite and migration from Mix. Vite is recommended; 2.x also retains ws_mix() and the Mix manifest integration. The WordPress queues below remain useful for plugin dependencies and native WordPress handles.

The resource manager queues dependencies for WordPress's native script/style functions:

php
// Frontend controller or provider
ws_enqueue_css('catalog', ws_asset('css/catalog.css'), [], '1.0.0');
ws_enqueue_js(
    'catalog',
    ws_asset('js/catalog.js'),
    ['jquery'],
    '1.0.0',
    true,
    ['CatalogConfig' => ['endpoint' => ws_url('/api/catalog')]]
);

The last JavaScript argument maps object names to data passed through wp_localize_script(). Dependencies are WordPress handles; scripts default to footer output.

Use the admin queue for admin pages:

php
ws_resources()->addAdminCss('sample-admin', ws_asset('css/admin.css'), [], '1.0.0');
ws_resources()->addAdminJs('sample-admin', ws_asset('js/admin.js'), ['jquery'], '1.0.0');

The manager registers queued definitions at init, then enqueues frontend assets on wp_enqueue_scripts:100 and admin assets on admin_enqueue_scripts:100. Register definitions with registerJs() / registerCss() when a resource should be available by handle without being immediately enqueued. Attach assets in the page controller to limit them to a matched page.

The ws_register_scripts action receives the resource manager after registration. Assets added after their queue has flushed are passed to WordPress immediately, but still need to be added before the corresponding script/style output point.

WordPress hooks must actually print the resources. Theme-preserving responses use the theme's hooks. A full-page Blade layout must include wp_head() and wp_footer() or manage its own asset tags; see full-page views.

Use explicit version arguments for predictable cache invalidation. The manager resolves sources through ws_asset(); generated URLs depend on app.asset_url.

See Resource Manager for configuration, existing handles, deferred localization data, JavaScript translations, and the browser callback queue.

Translation ​

The skeleton loads a WordPress text domain in AppServiceProvider::boot():

php
use WpStarter\Wordpress\Facades\L10n;

L10n::loadDomain('app', ws_resource_path('lang'));

The loader first checks WP_LANG_DIR/plugins/app-{locale}.mo, then resources/lang/{locale}.mo. Its locale comes from the application configuration, normally WordPress's determine_locale().

Use WordPress's functions with a domain, or the facade's default domain:

php
$text = __('Save', 'app');
$text = L10n::__('Save');
$text = L10n::_x('Post', 'noun');
$text = L10n::_n('One item', '%s items', $count);

The first loaded domain becomes the facade's default unless you set another with L10n::setDefaultDomain(). Escape translated text according to where it is rendered.

Laravel-style translation files use ws_trans() or ws___() and remain separate from WordPress .mo files. The global __() function belongs to WordPress; ws___() is the framework equivalent of Laravel's __() helper. Use the Laravel documentation for the framework translation API; use the WordPress domain integration when sharing translations with WordPress code.

WordPress integration, with Laravel-style application APIs.