Best Practices

Best Practices

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.