README

Muckidrive is a foundation for building web services on top of the Shopware 6.7 Core framework. It is not a webshop. It uses Shopware as an application framework (DAL, DI, events, messaging, migrations, Admin API) and leaves out Checkout, Storefront and all commerce logic.

shopware/core ~v6.7.0   ← Base framework (DAL, DI, Events, Migrations)
muckiware/core          ← Selective loader: only the required Shopware Core bundles
muckiware/master        ← Customized administration (without shop UI)
custom/plugins/*        ← Your web services, built as regular Shopware plugins

Requirements

Tool	Version
PHP	8.4
MySQL	8.4
Composer	2.x
Node.js / npm	for building the administration
DDEV	recommended local environment

Getting started

Install via Composer

composer create-project muckiware/muckidrive my-project

This works out of the box once muckiware/muckidrive is listed on Packagist. Until then, pass the GitHub repository explicitly:
composer create-project muckiware/muckidrive my-project \
  --repository='{"type":"vcs","url":"https://github.com/muckiware/muckidrive"}'

composer create-project downloads a thin skeleton (essentially composer.json) and installs the packages. Symfony Flex then generates the project files from the muckidrive recipes (muckiware/recipes): public/index.php, bin/console, bin/build-*.sh, the .htaccess files, config/bundles.php (without Checkout/Storefront), .env and the custom/* directories. Because these files come from recipes, they can be updated later - see Updating.

Initialize a git repository and commit right away, including composer.lock - recipe updates are applied as a 3-way merge on a clean working tree:

cd my-project
git init && git add -A && git commit -m "chore: create muckidrive project"

Or clone the repository (muckidrive development)

git clone https://github.com/muckiware/muckidrive.git my-project
cd my-project
composer install

The repository is also the development workspace of muckidrive itself: it contains the generated project files and symfony.lock, which are excluded from the create-project package via export-ignore in .gitattributes. Use create-project for your own projects.

First boot

Configure the environment. Flex creates .env with a generated APP_SECRET and INSTANCE_ID; put machine-specific values into .env.local (.env.example serves as a reference):
- DATABASE_URL - MySQL 8 database
- APP_SECRET / INSTANCE_ID - generated by Flex; to create new ones use openssl rand -hex 32 and openssl rand -base64 24 | tr -d /+
- MUCKIWARE_ROOT - absolute project path (/var/www/html inside DDEV)

Install the database and the basic system setup:

bin/console system:install --create-database \
  --shop-name "My project" --shop-email "admin@example.com" --shop-locale "en-GB" \
  --skip-assets-install --skip-first-run-wizard --no-assign-theme

Create an admin user:

bin/console user:create --admin --password <password> --email admin@example.com \
  --firstName Admin --lastName User admin

Build the administration UI:
```
bin/build-administration.sh
```

In DDEV, prefix the console with ddev exec (ddev exec bin/console ...) so PHP 8.4 from the container is used.

Updating

Update the packages with Composer and the generated project files with the Flex recipes (requires a clean git working tree):

composer update
composer recipes                              # list outdated recipes
composer recipes:update muckiware/core
composer recipes:update muckiware/master

Projects created from v0.1.0 - v0.1.4 need a one-time migration to the muckidrive recipes first. Both procedures are described in UPGRADE.md.

Architecture

Active bundles

The bundles are configured in config/bundles.php. Shopware\Core\Checkout\Checkout and the Storefront are deliberately disabled.

Bundle	Purpose
`Muckiware\Core\Framework\Framework`	Framework services: API, Cache, Filesystem, Plugin, Script, Webhook
`Muckiware\Core\System\System`	System services: Country, CustomEntity, Locale, User, Integration, Tag
`Muckiware\Core\Content\Content`	Content services: Cookie, Media, CMS, MailTemplate, Flow
`Muckiware\Master\Administration`	Administration UI without shop modules
`Shopware\Core\Maintenance\Maintenance`	Shopware maintenance commands
`Shopware\Core\Profiling\Profiling`	Profiling
`Shopware\Core\Service\Service`	Shopware service layer

muckiware/core

Namespace Muckiware\Core\. Each sub-bundle loads only the Shopware Core service definitions it needs, straight from vendor/shopware/core, not the whole Shopware stack. Helper::getFolderByClassName() finds the Shopware Core path at runtime.

muckiware/master

Namespace Muckiware\Master\. This is a customized version of the Shopware administration:

Backend: controllers for the admin UI, search, tags, user config, notifications and system info
Frontend: Vue 3 + Twig.js, Vite (pentatrion/vite-bundle), Pinia, Vue Router, TypeScript, Jest

Development

Build the administration

bin/build-administration.sh   # production build
bin/watch-administration.sh   # watch mode
bin/build-js.sh               # all JS assets

Inside custom/muckiware/master/Resources/app/administration/:

npm run build    # production build
npm run watch    # development watch
npm run unit     # Jest unit tests
npm run eslint   # linting

Console

Run PHP commands inside the DDEV container so that PHP 8.4 is used:

ddev exec bin/console cache:clear
ddev exec bin/console plugin:refresh

Writing plugins

Web services live in custom/plugins/ as standard Shopware plugins (they extend Shopware\Core\Framework\Plugin):

ddev exec bin/console plugin:refresh
ddev exec bin/console plugin:install --activate YourPluginName

Plugins that depend on Checkout, Storefront, products, customers or sales channels will not run on Muckidrive, because those parts of Shopware are not loaded.

Example: MuckiLogPlugin (separate repository) is a Log4php-based logging plugin with a custom entity, a migration, a scheduled task and an exception subscriber.

Conventions

declare(strict_types=1);, PSR-12, final by default
Namespace prefix Muckiware\ for core components
Services are defined in XML (services.xml)
To extend Shopware Core services, use decorators (XyzDecorator decorates Xyz)
Code, comments, commits and docs are written in English

Releases & changelog

Development happens on main; every user-visible change gets an entry in changelog/_unreleased/ - one small markdown file per change.
A release version is created only by merging (or pushing) main into the release branch. The release workflow then verifies that the release dist (built with git archive, i.e. without the export-ignored files) installs via composer create-project and that the recipes ran, computes the next version (patch bump of the latest tag - an explicit version can be given via Run workflow), moves the unreleased changelog entries into changelog/release-<x-y-z>/ (syncing the move back to main), tags, publishes the GitHub release and triggers the MuckiSafe image build.
Pushing a Git tag alone does nothing - versions are created only through the release branch.

The ready-to-run Docker distribution (MuckiSafe, ghcr.io/muckiware/muckisafe) lives in muckiware/MuckiSafe.

muckiware / muckidrive

Package info

Security

Statistics