README

ClassKit is a curated helper library for Concrete CMS package development. It centralizes the repetitive work that shows up across Limegreentangerine projects: package setup, page listing patterns, localized content helpers, API access, environment checks, file imports, and lightweight entity/search utilities.

Overview

ClassKit is designed to be consumed by Concrete CMS packages instead of being a standalone application. The goal is to keep common package logic in one place while keeping the surface area small and easy to extend.

The library helps with:

package lifecycle management and installation hooks
common Concrete CMS package traits for attributes, blocks, themes, pages, and storage
page and AJAX-page helpers for list rendering and pagination
localization and global-area helpers for multilingual builds
environment-aware configuration checks
cached search flows and reusable result helpers
API request wrappers and response handling
remote file import utilities and logging patterns
simple Doctrine-style entity base classes

Requirements

PHP 8.4+
Concrete CMS 9.2+
Composer 2.x

Installation

Install the package via Composer:

composer require limegreentangerine/class_kit

When working in a local package workspace, make sure Composer autoloading is enabled in the Concrete CMS environment where the consuming package is loaded.

Quick start

Use the base package controller as the foundation for your package:

use ClassKit\Package\PackageController;
use ClassKit\Package\Traits\AttributeTrait;
use ClassKit\Package\Traits\PageTrait;
use ClassKit\Package\Traits\ThemeTrait;

class MyPackageController extends PackageController
{
    use AttributeTrait;
    use PageTrait;
    use ThemeTrait;

    protected $pkgHandle = 'my_package';
    protected $pkgVersion = '1.0.0';
}

This gives you a consistent package bootstrap with common install hooks, service registration, and reusable setup helpers.

Included helpers

ClassKit currently includes the following capabilities:

Page and page-list extensions for attribute-topic filtering and search use cases
Global area localization for multilingual page layouts
Shared package controller and package interface abstractions
Environment checks for local, staging, and production workflows
Cached search helper for content and page lookups
File import utilities for bringing remote images into the Concrete file manager
API request base classes for JSON/XML integrations
Logger abstraction and standard response wrappers
Base entity classes for simple Doctrine-backed models
AJAX page response helpers for paginated card-based content views

Package traits

The package includes reusable traits in src/Package/Traits for common Concrete CMS package setup tasks. These traits are intended for package controllers or installer classes that need consistent configuration and registration logic.

Available traits:

AttributeTrait - create attribute types, sets, keys, select options, and page-type composer controls
BlockTrait - install block types, register block type sets, and add page-type composer block controls
ExpressTrait - create Express objects, generate simple forms, and manage default view/edit forms
FileTrait - create file sets and reuse the remote image import helpers
PageTrait - add pages, page types, and publish targets
StorageTrait - register remote or custom storage types
ThemeTrait - install or fetch page themes by handle

Example:

use ClassKit\Package\Traits\AttributeTrait;
use ClassKit\Package\Traits\PageTrait;
use ClassKit\Package\Traits\ThemeTrait;

class MyPackageController extends PackageController
{
    use AttributeTrait;
    use PageTrait;
    use ThemeTrait;
}

These traits simplify package installation and configuration while preserving a predictable pattern that is easy to reason about across multiple codebases.

Package structure

src/
├── Api/
│   ├── ConnectionController.php
│   ├── Enum/
│   │   ├── RequestMethod.php
│   │   └── ResponseType.php
│   ├── Interface/
│   │   ├── ConnectionInterface.php
│   │   └── ResponseInterface.php
│   └── Response/
│       ├── ErrorResponse.php
│       └── Response.php
├── Area/
│   └── GlobalArea.php
├── Entity/
│   └── Core/
│       ├── BaseEntity.php
│       ├── GuidEntity.php
│       ├── UpdatedEntity.php
│       └── UpdatedGuidEntity.php
├── Environment/
│   └── Environment.php
├── File/
│   └── ImportFileTrait.php
├── Log/
│   └── Logger.php
├── Package/
│   ├── Events/
│   │   └── PackageInstallEvent.php
│   ├── Traits/
│   │   ├── AttributeTrait.php
│   │   ├── BlockTrait.php
│   │   ├── ExpressTrait.php
│   │   ├── FileTrait.php
│   │   ├── PageTrait.php
│   │   ├── StorageTrait.php
│   │   └── ThemeTrait.php
│   ├── PackageController.php
│   └── PackageInterface.php
├── Page/
│   ├── AjaxPage/
│   │   ├── AjaxPage.php
│   │   ├── AjaxPageConfig.php
│   │   ├── AjaxPageRequest.php
│   │   ├── AjaxPageResponse.php
│   │   └── Enums/
│   │       └── SortOrder.php
│   ├── Theme/
│   │   └── Theme.php
│   ├── Page.php
│   ├── PageList.php
│   └── TranslationAdaptorTrait.php
├── Search/
│   ├── CachedSearch.php
│   ├── ItemList/
│   │   └── ListTrait.php
│   ├── Result/
│   │   └── Item/
│   │       └── ItemTrait.php
│   └── Result.php
controller.php

Example usage

Environment checks

use ClassKit\Environment\Environment;

if (Environment::isLocal()) {
    // Local-only setup
}

if (Environment::isProduction()) {
    // Production-only setup
}

Localized global area

use ClassKit\Area\GlobalArea;

$area = new GlobalArea('Header');

This helps produce locale-aware area handles for multilingual pages.

Page list filtering

use ClassKit\Page\PageList;

$pageList = new PageList();
$pageList->filterByMultipleTopics([
    [
        'handle' => 'topics',
        'topic' => 42,
    ],
    [
        'handle' => 'related_topics',
        'topic' => 'Example Topic',
    ],
], 'AND');

Cached search results

use ClassKit\Search\CachedSearch;

$search = new CachedSearch(Logger::class, 'search_results', 3600);
$ids = $search->search(
    MySearchClass::class,
    '/search',
    ['category' => 'news'],
    function ($list) {
        $list->filterByKeywords('concrete5');
    }
);

API client base class

use ClassKit\Api\ConnectionController;

class MyApi extends ConnectionController
{
    public function __construct()
    {
        parent::__construct('https://api.example.com', 'json', [
            'Authorization' => 'Bearer token',
        ]);
    }
}

The API base class centralizes request URL construction, payload encoding, header management, and response handling for JSON or XML APIs.

File import helper

use ClassKit\File\ImportFileTrait;

class MyPackageController
{
    use ImportFileTrait;

    public function importFromRemoteUrl(string $imageUrl): void
    {
        $file = $this->importImage($imageUrl, 'Products', 'Imported Images');
    }
}

Base entity pattern

use ClassKit\Entity\Core\BaseEntity;

class Product extends BaseEntity
{
    protected string $name;

    public function getName(): string
    {
        return $this->name;
    }
}

This gives a consistent foundation for package entity classes that need standard ID lookups and Doctrine-friendly structure.

Development

Run the package test suite using Composer:

composer test

Additional formatting and validation commands are available:

composer format

This runs the following formatting commands:

composer run format:php
composer run format:js

Check formatting without changes:

composer run format:php:check
composer run format:js:check

Notes

This project is a shared helper package, not a standalone customer-facing application.
It is intended to be consumed by Concrete CMS packages that need a common base layer across multiple projects.
The package includes conventions and reusable abstractions for standard Concrete CMS package workflows.

License

ClassKit is released under the MIT License. See LICENSE.TXT for details.

limegreentangerine / class_kit

Package info

Security

Statistics