Extension Development

Extension Development Guidelines

This document provides essential guidelines for developing third-party extensions for WebifyCMS.

Reserved Global Functions

WebifyCMS core (ext-base) defines the following global helper functions. Third-party extensions must NOT declare functions with these names to avoid fatal conflicts.

Application & Environment Functions

Function	Description
app()	Returns the web application instance
console_app()	Returns the console application instance
is_dev()	Checks if running in development environment
is_debug()	Checks if debug mode is enabled
dependency()	Returns the dependency service instance

Environment Variable Functions

Function	Description
load_env_variables(string $path, string $fileName = '.env')	Loads environment variables from .env file
get_env_variable(string $name, mixed $default = null)	Gets an environment variable value

Logging Functions

Function	Description
log_message(string $type, array|string $message, string $category = 'application')	Logs messages (supports: info, warning, debug, trace)

Alias Functions

Function	Description
set_alias(string $alias, string $path)	Sets a path alias
get_alias(string $alias)	Resolves a path from an alias

URL & Routing Functions

Function	Description
url(array|string $url, bool|string $scheme = false)	Creates a URL based on route parameters
request_url()	Returns the current requested URL
home_url(bool|string $scheme = false)	Returns the home URL
remember_url(array|string $url, ?string $name = null)	Remembers a URL for later retrieval
previous_url(?string $name = null)	Returns the previously remembered URL

Administration Functions

Function	Description
administration()	Returns the administration service instance
administration_path()	Returns the administration path
administration_url(array|string|null $url = null, bool|string $scheme = false)	Creates an administration URL
in_administration()	Checks if currently in administration area

View Functions

Function	Description
view()	Returns the framework's view component

Translation Functions

Function	Description
translate(string $category, string $message, array $params = [], ?string $language = null)	Translates a string

Reserved Constants

Constant	Value	Description
ENV_PRODUCTION	'prod'	Production environment identifier
ENV_DEVELOPMENT	'dev'	Development environment identifier

---

Best Practices for Extension Developers

1. Use Unique Function Names

Prefix your helper functions with your extension's unique identifier:

// ❌ BAD - May conflict with core or other extensions
function log_message() { }
function url() { }

// ✅ GOOD - Unique to your extension
function my_extension_log_special() { }
function my_extension_custom_url() { }

2. Check Before Declaring (Optional Safety)

If you want to provide fallback implementations or avoid conflicts:

if (!function_exists('my_extension_helper')) {
    function my_extension_helper() {
        // Your implementation
    }
}

3. Use Namespaced Classes Over Global Functions

For extension-specific functionality, prefer namespaced classes:

namespace MyVendor\MyExtension\Helper;

class UrlHelper {
    public static function generateCustomUrl(): string {
        // Your implementation
    }
}

// Usage:
use MyVendor\MyExtension\Helper\UrlHelper;
UrlHelper::generateCustomUrl();

4. Leverage Core Functions

Instead of redefining functionality, use WebifyCMS core helper functions:

// ✅ Use core functions
function my_extension_admin_dashboard_url(): string {
    return administration_url('my-extension/dashboard');
}

function my_extension_log_error(string $message): void {
    log_message('error', "[MyExtension] {$message}", 'my-extension');
}

5. Document Your Helper Functions

Always document your global helper functions in your extension's README:

## Helper Functions

This extension provides the following global helper functions:

- `my_extension_do_something()` - Does something useful
- `my_extension_format_output()` - Formats output in a specific way

---

Autoloading Your Helpers

If your extension needs to define helper functions, register them in your composer.json:

{
    "name": "vendor/my-extension",
    "autoload": {
        "psr-4": {
            "MyVendor\\MyExtension\\": "src/"
        },
        "files": [
            "src/helpers.php"
        ]
    }
}

Important: Composer loads files in the order they're defined across all packages. WebifyCMS core helpers will load first, so never redefine core function names.

---

Troubleshooting

Fatal Error: Cannot Redeclare Function

If you encounter this error:

Fatal error: Cannot redeclare log_message() in /path/to/extension/helpers.php

Solution: Your extension is trying to define a function that already exists in the core. Choose a different, unique function name.

Function Not Found After Installation

If your helper function isn't available:

1. Ensure composer.json includes your helpers file in the files autoload section
2. Run composer dump-autoload to regenerate the autoloader
3. Clear any application caches

---

Need Help?

• Check the WebifyCMS Documentation
• Review the core helper functions in vendor/webifycms/ext-base/src/helpers.php
• Ask questions in the WebifyCMS Community

---

Last Updated: 2025-12-06