### Basic FOF Joomla! Installation Script Structure

Source: https://github.com/akeeba/fof/wiki/The-InstallScript-class

Provides the fundamental structure for a Joomla! installation script that extends FOF's InstallScript class. It includes necessary checks for FOF inclusion and defines component-specific properties.

```php
<?php
// no direct access
defined('_JEXEC') or die();

// Load FOF if not already loaded
if (!defined('FOF30_INCLUDED') && !@include_once(JPATH_LIBRARIES . '/fof30/include.php'))
{
	throw new RuntimeException('This component requires FOF 3.0.');
}

class Com_FoobarInstallerScript extends \FOF30\Utils\InstallScript
{
    protected $componentName = 'com_foobar';
    protected $componentTitle = 'Foobar Component';
}
```

--------------------------------

### Component Package Layout

Source: https://github.com/akeeba/fof/wiki/The-InstallScript-class

Illustrates the recommended directory structure for Joomla! component packages, including backend, frontend, media, cli, and language files. The installation script handles the 'cli' directory specifically.

```text
<root>
  +-- backend   Component files under site's "administrator" directory
  +-- frontend  Component files under site's root director
  +-- media     OPTIONAL. Component media files, under site's "media" directory
  +-- cli       OPTIONAL. Component CLI script installed under site's "cli" directory
  +-- language  OPTIONAL. Language files for your component.
```

--------------------------------

### FOF Joomla! Installation Script Component Properties

Source: https://github.com/akeeba/fof/wiki/The-InstallScript-class

Defines essential properties for the FOF installation script, specifying the component's internal name and its human-readable title. These are used by the FOF framework for registration and management.

```php
{
    protected $componentName = 'com_foobar';
    protected $componentTitle = 'Foobar Component';
}
```

--------------------------------

### Joomla! Manifest Script File Declaration

Source: https://github.com/akeeba/fof/wiki/The-InstallScript-class

Declares the installation script file within the Joomla! component's XML manifest. This line specifies the name and location of the script file that Joomla! will execute during installation or uninstallation.

```xml
<scriptfile>script.com_foobar.php</scriptfile>
```

--------------------------------

### FOF Library Inclusion Check

Source: https://github.com/akeeba/fof/wiki/The-InstallScript-class

Checks if the FOF 3.0 library is already included and attempts to load it if not. This is crucial as the installation script relies on FOF's functionality.

```php
// Load FOF if not already loaded
if (!defined('FOF30_INCLUDED') && !@include_once(JPATH_LIBRARIES . '/fof30/include.php'))
{
	throw new RuntimeException('This component requires FOF 3.0.');
}
```

--------------------------------

### Configuration File Setup

Source: https://github.com/akeeba/fof/blob/development/Tests/README.md

Copy the distribution configuration file to a new file and update its contents to point to your local testing environment, such as database credentials and site root.

```bash
cp Tests/config.dist.php Tests/config.php
```

--------------------------------

### FOF 3 Component Structure Setup

Source: https://github.com/akeeba/fof/wiki/Migrating-components-from-FOF-2-to-FOF-3

Initial steps for setting up a new FOF 3 component, including the manifest file and basic component structure. This involves defining namespaces and factory configurations.

```xml
<install>
  <name>YourComponentName</name>
  <version>1.0.0</version>
  <namespace>MyCompany\MyApp</namespace>
  <fof>
    <backend factory="MagicSwitch"/>
    <frontend factory="Basic"/>
  </fof>
</install>
```

```php
// myapp.php (main entry point)
require_once 'path/to/fof/autoload.php';

$app = FOF3\Application::getInstance();
$app->dispatch();
```

--------------------------------

### FOF Database Installer Class Constructor

Source: https://github.com/akeeba/fof/wiki/The XML Database Schema Installer

Initializes the FOF Database Installer class. It requires a database object and the directory path to the XML schema files. The directory parameter can be overridden from the default 'sql/xml'.

```apidoc
FOF30\Database\Installer(db, directory)
  - db: The database object used to execute SQL commands. Use JFactory::getDbo() if unsure.
  - directory: The absolute filesystem path where the XML schema files are located. Defaults to 'sql/xml'.
```

--------------------------------

### FOF Joomla! Installation Script Class Naming Convention

Source: https://github.com/akeeba/fof/wiki/The-InstallScript-class

Illustrates the strict naming convention required for Joomla! installation scripts that extend FOF's InstallScript. The class name must follow the pattern 'Com_ComponentNameInstallerScript' with precise capitalization.

```php
class Com_FoobarInstallerScript extends \FOF30\Utils\InstallScript
```

--------------------------------

### FOF Database Installer Methods

Source: https://github.com/akeeba/fof/wiki/The XML Database Schema Installer

Provides methods to manage database schemas. `updateSchema()` creates or updates tables, and `removeSchema()` drops tables. These methods are crucial for component installation, updates, and uninstallation.

```apidoc
public function updateSchema()
  - Description: Creates or updates the tables of your component in the database.
  - Usage: Recommended to call in installation scripts and the main back-end page of your component to handle updates even without re-installation.
  - Behavior: Executes SQL commands based on table/field existence or custom SQL queries defined in XML schema files.

public function removeSchema()
  - Description: Removes (drops) the tables of your component.
  - Usage: Recommended only for the uninstallation script of your component.
  - Warning: Permanently removes all database tables defined in the XML schema file without further warning.
```

--------------------------------

### Composer Dependency Management

Source: https://github.com/akeeba/fof/blob/development/Tests/README.md

Install project dependencies using Composer. If you need to update the dependencies to their latest versions, use the update command.

```composer
composer install
```

```composer
composer update
```

--------------------------------

### Model Header Field Configuration Example

Source: https://github.com/akeeba/fof/wiki/Model-Header

Illustrates the structure and attributes for configuring a Model Header field. This example shows how to specify the data model, key and value fields, translation, access control, placeholder text, and state-based filtering.

```XML
<header
	name="example"
	type="Model"
	model="com_example.Items"
	key_field="example_item_id"
	value_field="title"
	translate="false"
	apply_access="true"
	none="COM_FOOBAR_ITEMS_MSG_NO_EXAMPLE_ITEM_SELECTED"
>
	<state key="enabled">1</state>
	<state key="language"><![CDATA[en_GB, *]]></state>
</header>
```

--------------------------------

### Joomla! Direct Access Prevention

Source: https://github.com/akeeba/fof/wiki/The-InstallScript-class

Standard Joomla! code snippet to prevent direct access to the script file. This ensures the script can only be executed within the Joomla! environment.

```php
// no direct access
defined('_JEXEC') or die;
```

--------------------------------

### PHP: Specify Files/Folders to Remove from All Versions

Source: https://github.com/akeeba/fof/wiki/The-InstallScript-class

Specifies files and folders to be removed from both free and paid versions of an extension. This is useful for refactoring code and cleaning up obsolete files. Paths are relative to the site's root.

```php
protected $removeFilesAllVersions = array(
  'files'   => array(
    'administrator/components/com_foobar/helpers/old_helper.php'
  ),
  'folders' => array(
    'administrator/components/com_foobar/old_feature'
  )
);
```

--------------------------------

### Example SQL Query within Action

Source: https://github.com/akeeba/fof/wiki/The XML Database Schema Installer

Shows an SQL INSERT statement executed as part of an action when its conditions are met.

```SQL
INSERT IGNORE INTO `#__admintools_profiles`
(`id`,`description`, `configuration`, `filters`) VALUES
(1,'Default PHP Change Scanner Profile','','');
```

--------------------------------

### Example Action with Conditional Insert

Source: https://github.com/akeeba/fof/wiki/The XML Database Schema Installer

This example demonstrates an action that inserts a default profile if a specific record does not exist. It uses an 'equals' condition with a 'not' operator to check the count of existing records.

```APIDOC
<action table="#__admintools_profiles" canfail="1">
  <condition type="equals" operator="not" value="1"><![CDATA[
SELECT COUNT(*) FROM `#__admintools_profiles` WHERE `id` = 1;
  ]]></condition>

  <query canfail="1"><![CDATA[
INSERT IGNORE INTO `#__admintools_profiles`
(`id`,`description`, `configuration`, `filters`) VALUES
(1,'Default PHP Change Scanner Profile','','');
  ]]></query>
</action>
```

--------------------------------

### PHP: Specify Files/Folders to Remove from Free Version

Source: https://github.com/akeeba/fof/wiki/The-InstallScript-class

Specifies files and folders to be removed exclusively from the free version of an extension. This is typically used when migrating features to a paid version. Paths are relative to the site's root.

```php
protected $removeFilesFree = array(
  'files'   => array(
    'administrator/components/com_foobar/helpers/whatever.php'
  ),
  'folders' => array(
    'administrator/components/com_foobar/baz'
  )
);
```

--------------------------------

### Example SQL Query within Condition

Source: https://github.com/akeeba/fof/wiki/The XML Database Schema Installer

Illustrates a SQL query used within an `<condition>` tag to check for the existence of a record.

```SQL
SELECT COUNT(*) FROM `#__admintools_profiles` WHERE `id` = 1;
```

--------------------------------

### Default MVC Class Extension Example

Source: https://github.com/akeeba/fof/wiki/The-Factory

Demonstrates how to extend a default MVC class provided by FOF when using the MagicSwitchFactory. This ensures your custom classes inherit the necessary base functionality.

```php
class Items extends DefaultDataModel
{
    // ....
}
```

--------------------------------

### Enable FOF Scaffolding via Container Initialization

Source: https://github.com/akeeba/fof/wiki/Scaffolding

Demonstrates how to enable the FOF Scaffolding feature and its auto-save functionality by passing parameters during the container instantiation. This is the primary method for enabling scaffolding when a component starts.

```php
$container = FOF30\Container\Container::getInstance('com_example', array(
	'scaffolding' => true,
	'saveScaffolding' => true,
))->dispatcher->dispatch();
```

--------------------------------

### Instantiate and Configure Download Helper (PHP)

Source: https://github.com/akeeba/fof/wiki/The Download Helper

Demonstrates how to create an instance of the FOF30\Download\Download helper class, passing the component's container. It also shows how to retrieve the active adapter name and configure adapter-specific options.

```php
$download = new FOF30\Download\Download($container);
$adapter = $download->getAdapterName();
$download->setAdapterOptions([
    CURLOPT_FOLLOWLOCATION => 0,
    CURLOPT_USERAGENT => 'AcmeExample/1.0',
]);
```

--------------------------------

### Get Current Extension Version

Source: https://github.com/akeeba/fof/wiki/The Update package

Demonstrates how to fetch the currently installed version of the extension using the getVersion() method. This is useful for comparing against available updates.

```php
$currentVersion = $container->model('MyUpdates')->getVersion();

```

--------------------------------

### Get Root Node using TreeModel in PHP

Source: https://github.com/akeeba/fof/wiki/The TreeModel

Retrieves the root node of the hierarchical data structure managed by FOF's TreeModel. This is the starting point for navigating the tree.

```php
$rootNode = $model->getRoot();
```

--------------------------------

### Initialize Chunked Download with importFromURL in PHP

Source: https://github.com/akeeba/fof/wiki/The Download Helper

This snippet demonstrates the initial setup for a chunked download using the importFromURL method. It outlines the essential configuration options required to specify the remote URL, local file path, chunk size, and execution time limits for the download process.

```php
$options = [
   // Setup
   'url'           => 'http://www.example.com/big.zip',
   'localFilename' => JPATH_SITE . '/tmp/big.zip',
   'maxExecTime'   => 5,
   'runTimeBias'   => 75,
   'length'        => 1048576,
   // Runtime
   'frag'          => -1,
   'totalSize'     => -1,
   'doneSize'      => -1,
];

$response = $download->importFromURL($options);
```

--------------------------------

### FOF 3 Component Entry Point

Source: https://github.com/akeeba/fof/wiki/Getting-started-with-a-FOF-component

This PHP script serves as the entry point for a FOF 3 component. It ensures FOF 3.0 is included, retrieves a component-specific container instance, and dispatches the component's execution. It's crucial to omit the closing PHP tag to prevent potential session issues.

```php
<?php

if (!defined('FOF30_INCLUDED') && !@include_once(JPATH_LIBRARIES . '/fof30/include.php'))
{
	throw new RuntimeException('FOF 3.0 is not installed', 500);
}

FOF30\Container\Container::getInstance('com_example')->dispatcher->dispatch();

```

--------------------------------

### Configure Update Site and Extra Query

Source: https://github.com/akeeba/fof/wiki/The Update package

Provides an example of setting multiple configuration parameters in the constructor, including the update site URL, site name, and an extra query string for authentication or specific parameters.

```php
class MyUpdates extends FOF30\Update\Update
{
	
	public function __construct($config = array())
	{
	  $config['update_component'] = 'com_foobar';
	  $config['update_sitename'] = 'Foobar updates';
	  $config['update_site'] = 'http://www.example.com/updates/com_foobar.xml';
	  $config['update_extraquery'] = 'authorisation=mySuperSecretCode';
	
	  parent::__construct($config);
	}
}

// Parameter descriptions:
// - update_sitename: Name of the update site.
// - update_site: URL to the update XML file.
// - update_extraquery: Appended to download URLs for authentication or custom parameters.

```

--------------------------------

### FOF Behavior Class Naming Convention Example

Source: https://github.com/akeeba/fof/wiki/Model-behaviors

Provides an example of how FOF determines the class name for a behavior, illustrating the search order for custom and framework-provided behaviors.

```php
/*
 * For component com_example, namespace Acme\Example\Admin, Items model, Filters behavior:
 * FOF will look for:
 * 1. Acme\Example\Admin\Model\Behaviour\Items\Filters
 * 2. Acme\Example\Admin\Model\Behaviour\Filters
 * 3. FOF30\Model\DataModel\Behaviour\Filters
 */
FOF30\Container\Container::getInstance('com_example')
    ->factory->model('Items', array('behaviours' => array('Filters')))->
```

--------------------------------

### Example `fof.xml` Configuration

Source: https://github.com/akeeba/fof/wiki/The-XML-configuration-file

This snippet demonstrates the typical structure of a `fof.xml` file used for configuring FOF components. It includes sections for common settings like container, dispatcher, authentication, model definitions with relations and behaviors, and view-specific configurations for task mapping, ACL, and toolbars.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<fof>
    <!-- Common settings -->
    <common>
        <!-- Container configuration -->
        <container>
            <option name="componentNamespace"><![CDATA[MyCompany\MyApplication]]></option>
        </container>

        <!-- Dispatcher configuration -->
        <dispatcher>
            <option name="defaultView">items</option>
        </dispatcher>
        
        <!-- Transparent authentication configuration -->
        <authentication>
            <option name="totpKey">ABCD123456</option>
            <option name="authenticationMethods">HTTPBasicAuth_TOTP,QueryString_TOTP</option>
        </authentication>

        <!-- Model configuration. One tag for each Model. -->
        <model name="orders">
            <!-- Model configuration -->
            <config>
                <option name="tbl"><![CDATA[#__fakeapp_orders]]></option>
            </config>
        
            <!-- Field aliasing. One tag per aliased field -->
            <field name="enabled">published</field>

            <!-- Relation setup. One tag per relation -->
            <relation type="hasMany" name="items" />
            <relation type="belongsToMany"
                      name="transactions"
                      localKey="foobar_order_id"
                      foreignKey="foobar_transaction_id"
                      pivotLocalKey="foobar_order_id"
                      pivotForeignKey="foobar_transaction_id"
                      pivotTable="#__foobar_orders_transactions" />
            <relation type="belongsTo" name="client" foreignModelClass="Users@com_fakeapp" />

            <!-- Behaviour setup. Use merge="1" to merge with already defined behaviours. -->
            <behaviors merge="1">foo,bar,baz</behaviors>
        </model>

        <!-- Controller, View and Toolbar setup. One tag per view. -->
        <view name="item">
            <!-- Controller task aliasing -->
            <taskmap>
                <task name="list">browse</task>
            </taskmap>
            
            <!-- Controller ACL mapping -->
            <acl>
                <task name="dosomething" />
                <task name="somethingelse">core.manage</task>
            </acl>
            
            <!-- Controller and View options -->
            <config>
                <option name="autoRouting">3</option>
            </config>
            
            <!-- Toolbar configuration -->
            <toolbar title="COM_FOOBAR_TOOLBAR_ITEM" task="edit">
                <button type="save" />
                <button type="saveclose" />
                <button type="savenew" />
                <button type="cancel" />
            </toolbar>
        </view>
    </common>
    
    <!-- Component backend options -->
    <backend>
        <!-- The same options as Common Settings apply here, too -->
    </backend>
    
    <!-- Component frontend options -->
    <frontend>
        <!-- The same options as Common Settings apply here, too -->
    </frontend>
</fof>
```

--------------------------------

### PHP Example: Internal vs. Plugin Event Handler Signatures

Source: https://github.com/akeeba/fof/wiki/Using Joomla! plugins to handle FOF events

Illustrates the difference in method signatures between an internal FOF event handler and a corresponding Joomla! plugin event handler using PHP code examples.

```php
<?php
// Internal FOF event handler signature within a DataModel class
protected function onBeforeSave(&$data) {
    // ... handler logic ...
}

// Corresponding Joomla! plugin event handler signature
// For a component 'com_example', model 'Item', event 'onBeforeSave'
protected function onComExampleModelItemBeforeSave($model, &$data) {
    // $model is an instance of the triggering model object
    // ... handler logic ...
}
?>
```

--------------------------------

### FOF 3 View and Controller Handling

Source: https://github.com/akeeba/fof/wiki/Migrating-components-from-FOF-2-to-FOF-3

Recommendations for creating FOF 3 view templates and controllers, emphasizing descriptive naming, using XML forms, and minimizing controller overrides.

```php
// Example: Setting ControlPanel view as default in Dispatcher
class Dispatcher extends FOF3\Dispatcher {
    protected function getApplicationConfiguration() {
        return [
            'default_view' => 'ControlPanel'
        ];
    }
}

// Example: Controller with minimal overrides
class MyViewController extends FOF3\Controller {
    // Override onBefore/onAfter events instead of main methods
    protected function onBeforeBrowse() {
        // Custom logic before browsing
        return parent::onBeforeBrowse();
    }
}
```

--------------------------------

### Accessing Item Data in FOF30 Views

Source: https://github.com/akeeba/fof/wiki/The-Raw-view

Demonstrates how to retrieve item data from FOF30 views. For browse views, it shows how to get the total item count and the collection of items. For read, add, or edit views, it shows how to get the single DataModel for the current item.

```PHP
// On browse views:
$count = $this->getItemCount();
$items = $this->getItems();

/** @var  DataModel  $item  Each item in the collection is a DataModel **/
foreach ($items as $item)
{
    // Render each item
}

// On read, add, edit views:
$item = $this->getItem();

```

--------------------------------

### Instantiate FOF Container with Factory

Source: https://github.com/akeeba/fof/wiki/The-Factory

Demonstrates how to instantiate the FOF Container and specify a custom factory class using an initialization parameter. This method is less recommended than using fof.xml for configuration.

```PHP
$container = FOF30\Container\Container::getInstance('com_example', array(
    'factoryClass' => 'MagicSwitch'
));
```

--------------------------------

### Run PHPUnit Test Suite

Source: https://github.com/akeeba/fof/blob/development/Tests/README.md

Execute the PHPUnit test suite from the Tests directory. This command requires the PHPUnit configuration file and the vendor directory to be set up correctly.

```bash
../vendor/bin/phpunit -c ../phpunit.xml
```

--------------------------------

### Get Model Instance via Controller

Source: https://github.com/akeeba/fof/wiki/The-Model

Provides a shortcut for retrieving a model instance when already within a controller context. This method typically returns the same object instance.

```php
$model = $this->getModel('MyModel');
```

--------------------------------

### Displaying Literal Curly Braces

Source: https://github.com/akeeba/fof/wiki/Blade-Templates

Shows how to display strings that start and end with curly braces without them being interpreted as Blade directives. Prefixing the string with an '@' symbol achieves this.

```blade
@{{ This line is not parsed by Blade }}
```

--------------------------------

### Perform Full Download (PHP)

Source: https://github.com/akeeba/fof/wiki/The Download Helper

Shows how to use the `getFromURL` method to download the entire content of a remote URL into a string. This method is suitable for smaller files that can be downloaded in a single operation.

```php
$contents = $download->getFromURL('http://www.example.com/example.txt');
```

--------------------------------

### Programmatic Data Source Example (PHP)

Source: https://github.com/akeeba/fof/wiki/XML-Form-Fields

Illustrates a PHP class and static method structure that can be used to programmatically provide options for a drop-down field in Akeeba FOF forms.

```PHP
namespace Acme\Example\Admin\Helper;

class Select
{
    /**
     * Provides data for a form field's options.
     *
     * @return array An array of options, e.g., [['value' => 'key1', 'text' => 'Label 1'], ['value' => 'key2', 'text' => 'Label 2']]
     */
    public static function getSomeFoobarData(): array
    {
        // In a real scenario, this might fetch data from a database or another source.
        return [
            ['value' => '1', 'text' => 'Option One'],
            ['value' => '2', 'text' => 'Option Two'],
            ['value' => '3', 'text' => 'Option Three'],
        ];
    }

    /**
     * Provides data as a JHtml options object.
     *
     * @return object A JHtml options object.
     */
    public static function getOptionsObjectData(): object
    {
        // Example using Joomla's JHtmlOptions
        // JLoader::registerNamespace('Joomla', JPATH_ADMINISTRATOR . '/libraries');
        // JLoader::import('joomla.html.options');
        // $options = new JHtmlOptions();
        // $options->add('Option A', 'a');
        // $options->add('Option B', 'b');
        // return $options;
        
        // Placeholder for demonstration
        return (object) ['Option A' => 'a', 'Option B' => 'b'];
    }
}
```

--------------------------------

### Get Container Instance

Source: https://github.com/akeeba/fof/wiki/The-Container

Retrieves the static container object instance for a specific component. It's recommended to configure the container via fof.xml rather than passing values directly.

```php
$container = FOF30\Container\Container::getInstance('com_foobar');
```

--------------------------------

### Read Component Parameters

Source: https://github.com/akeeba/fof/wiki/Component-Parameters-Service

Demonstrates how to retrieve configuration parameter values from the service. It shows how to get a specific parameter with an optional default value and how to reload all parameters from the database if they have changed.

```php
$yourParam = $this->container->params->get('paramName', 'defaultValue');
$this->container->params->reload();
```

--------------------------------

### Loading Behaviors via Factory

Source: https://github.com/akeeba/fof/wiki/Model-behaviors

Shows how to load behaviors when obtaining a model instance through the FOF factory. This allows for dynamic behavior loading based on specific use cases.

```php
$model = $this->container->factory->model('Items', array('behaviours' => array('Filters', 'ContentHistory')));
```

--------------------------------

### Render JLayout using JLayoutFile (PHP)

Source: https://github.com/akeeba/fof/wiki/The Layout package

Illustrates the traditional Joomla way of rendering a JLayout using the JLayoutFile class. This approach requires manual instantiation of the layout object.

```PHP
$layout = new JLayoutFile('joomla.content.helloworld');
$data = array('name' => 'Bob');
echo $layout->render($data);
```