README

Smarty ForeachQ

Backward compatibility foreach implementation for legacy XOOPS and ImpressCMS templates

Rewritten (due that original use GPLv2+ license) Smarty foreach variant that was invented for use in XOOPS, but nowadays used in some other PHP based CMS'es (like ImpressCMS!).

See, original version of this smarty plugin in Xoops to see more accurate description why this plugin exists.

Installation

To install and use this package, we recommend to use Composer:

composer require imponeer/smarty-foreachq

Otherwise, you need to include manually files from src/ directory.

Setup

Basic Setup

To register the ForeachQ extension with Smarty, add the extension class to your Smarty instance:

// Create a Smarty instance
$smarty = new \Smarty\Smarty();

// Register the ForeachQ extension
$smarty->addExtension(new \Imponeer\Smarty\Extensions\ForeachQ\ForeachQExtension());

Using with Symfony Container

To integrate with Symfony, you can leverage autowiring, which is the recommended approach for modern Symfony applications:

# config/services.yaml
services:
    # Enable autowiring and autoconfiguration
    _defaults:
        autowire: true
        autoconfigure: true

    # Register your application's services
    App\:
        resource: '../src/*'
        exclude: '../src/{DependencyInjection,Entity,Tests,Kernel.php}'

    # Configure Smarty with the extension
    # The ForeachQExtension will be autowired automatically
    \Smarty\Smarty:
        calls:
            - [addExtension, ['@Imponeer\Smarty\Extensions\ForeachQ\ForeachQExtension']]

Then in your application code, you can simply retrieve the pre-configured Smarty instance:

// Get the Smarty instance with the ForeachQ extension already added
$smarty = $container->get(\Smarty\Smarty::class);

Using with PHP-DI

With PHP-DI container, you can take advantage of autowiring for a very simple configuration:

use function DI\create;
use function DI\get;

return [
    // Configure Smarty with the extension
    \Smarty\Smarty::class => create()
        ->method('addExtension', get(\Imponeer\Smarty\Extensions\ForeachQ\ForeachQExtension::class))
];

Then in your application code, you can retrieve the Smarty instance:

// Get the configured Smarty instance
$smarty = $container->get(\Smarty\Smarty::class);

Using with League Container

If you're using League Container, you can register the extension like this:

// Create the container
$container = new \League\Container\Container();

// Register Smarty with the ForeachQ extension
$container->add(\Smarty\Smarty::class, function() {
    $smarty = new \Smarty\Smarty();

    // Configure Smarty...

    // Create and add the ForeachQ extension
    $extension = new \Imponeer\Smarty\Extensions\ForeachQ\ForeachQExtension();
    $smarty->addExtension($extension);

    return $smarty;
});

Then in your application code, you can retrieve the Smarty instance:

// Get the configured Smarty instance
$smarty = $container->get(\Smarty\Smarty::class);

Usage

Simple iteration:

{foreachq from=$users item=user}
    <p>User: {$user.name}</p>
{/foreachq}

With key and item:

{foreachq from=$data key=index item=value}
    <p>{$index}: {$value}</p>
{/foreachq}

Nested loops:

{foreachq from=$categories item=category}
    <h2>{$category.name}</h2>
    {foreachq from=$category.items item=item}
        <p>- {$item.title}</p>
    {/foreachq}
{/foreachq}

Development

Code Quality Tools

This project uses several tools to ensure code quality:

PHPUnit - For unit testing

composer test

PHP CodeSniffer - For coding standards (PSR-12)

composer phpcs    # Check code style
composer phpcbf   # Fix code style issues automatically

PHPStan - For static analysis

composer phpstan

Documentation

API documentation is automatically generated and available in the project's wiki. For more detailed information about the classes and methods, please refer to the project wiki.

Contributing

Contributions are welcome! Here's how you can contribute:

Fork the repository
Create a feature branch: git checkout -b feature-name
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin feature-name
Submit a pull request

Please make sure your code follows the PSR-12 coding standard and include tests for any new features or bug fixes.

If you find a bug or have a feature request, please create an issue in the issue tracker.

imponeer / smarty-foreachq

Maintainers

Details