To ensure your custom applications are maintainable, secure, and compatible with future SDK versions, we recommend following these best practices:
Project Structure & Organization
•Keep each application in its own folder within custom_applications/. Avoid mixing files.
•Use clear, lowercase, dash-separated folder names (e.g. user-stats, data-export).
•Keep logic modular — extract reusable code into helper files within your application.
Working with the SDK
•Always use type hints and use statements for SDK interfaces in your closure — injection depends on them.
•The order of injected interfaces in the closure does not matter.
•Don’t try to instantiate SDK interfaces manually — the SDK will inject them for you automatically.
Error Handling & Debugging
•Catch and handle exceptions using try/catch blocks — especially when working with user input or the database.
•Avoid exposing raw error messages to users. Use logging if available.
•Use var_dump(), echo, or a debug log to inspect data during development — but remove them before production.
Security & Input Validation
•Always sanitize and validate input, especially when using query parameters or working with user data.
•Never use raw SQL with unsanitized values — use proper quoting or prepared statements.
•Be cautious with output — encode values if embedding them in HTML.
Routing & URLs
•Use /custom-applications/ in the URL (with a dash) — never /custom_applications/.
•Don’t rename the custom_applications/ directory on disk to match the URL — they are intentionally different.
Dependency Management
•Run all composer commands in the root of custom_applications/ where composer.json lives.
•Don’t install the SDK globally or outside the app directory — apps rely on local autoloading via Composer.
Development Workflow
•Start with the Quickstart example to validate your setup.
•Use a browser and URL-based testing for simple apps.
