What is PrestaSpirit?

PrestaSpirit is a Composer package repository. It lets you find PrestaShop modules and lets Composer know where to get the code from. You can use Composer to manage your modules' dependencies - read more about it on the Composer website.

How to submit modules?

Naming your module

First of all, you must pick a module name. This is a very important step since it can not change and it should be unique enough to avoid conflicts in the future.

The module name consists of a vendor name and a project name joined by a /. The vendor name exists to prevent naming conflicts. For example, by including a vendor name both igorw and seldaek can have a module named slider by naming their packages igorw/slider and seldaek/slider.

In some cases the vendor name and the module name may be identical. An example of this would be `paypal/paypal`. For projects with a unique name this is recommended. It also allows adding more related modules under the same vendor later on. If you are maintaining a library, this would make it really easy to split it up into smaller decoupled parts.

Note that module names are case-insensitive, but it's encouraged to use a dash (-) as separator instead of CamelCased names.

Creating a composer.json file

The composer.json file should reside at the top of your module's git/svn/.. repository, and is the way you describe your module to both PrestaSpirit and composer.

A typical composer.json file looks like this:

{
    "name": "frederic-benoist/fbsample_advconfig",
    "description": "Sample automatic setup PrestaShop 1.7 Module.",
    "authors": [
      {
        "name": "Frédéric BENOIST",
        "homepage": "https://www.fbenoist.com/"
      }
    ],
    "require": {
      "php": ">=5.6.0"
    },
    "config": {
      "preferred-install": "dist"
    },
    "type": "prestashop-module",
    "license": "AFL-3.0",
    "homepage": "https://github.com/frederic-benoist/fbsample-advconfig"
  }
  

Most of this information is obvious, keywords are tags, require are list of dependencies that your module has. This can of course be modules, not only a php version. You can use ext-foo to require php extensions (e.g. ext-curl). Note that most extensions don't expose version information, so unless you know for sure it does, it's safer to use "ext-curl": "*" to allow any version of it. Finally the type field is in this case indicating that this is a library.

Once you have this file committed in your repository root, you can submit the module to PrestaSpirit by entering the public repository URL.

Managing module versions

New versions of your module are automatically fetched from tags you create in your VCS repository.

The easiest way to manage versioning is to just omit the version field from the composer.json file. The version numbers will then be parsed from the tag and branch names.

Tag/version names should match 'X.Y.Z', or 'vX.Y.Z', with an optional suffix for RC, beta, alpha or patch versions. Here are a few examples of valid tag names:

1.0.0
v1.0.0
1.10.5-RC1
v4.4.4beta2
v2.0.0-alpha
v2.0.4-p1

Branches will automatically appear as "dev" versions that are easily installable by anyone that wants to try your module, but that does not mean you should not tag releases. The use of Semantic Versioning is strongly encouraged.

Update Schedule

New modules will be crawled immediately after submission if you have JS enabled.

Existing modules without auto-updating (GitHub/BitBucket hook) will be crawled once a week for updates. When a hook is enabled modules are crawled whenever you push, or at least once a month in case the crawl failed. You can also trigger a manual update on your module page if you are logged-in as a maintainer.

It is highly recommended to set up the GitHub/BitBucket service hook for all your modules. This reduces the load on our side, and ensures your module is updated almost instantly. Check the how-to below.

The search index is updated every five minutes. It will index (or reindex) any module that has been crawled since the last time the search indexer ran.

How to update modules?

GitHub Hook

Enabling the PrestaSpirit service hook ensures that your module will always be updated instantly when you push to GitHub.

To do so you can:

  • Make sure you login via GitHub (if you already have an account not connected to GitHub, you can connect it on your profile). If you are logged in already, log out first then login via GitHub again to make sure you grant us the required permissions.
  • Make sure the PrestaSpirit application has access to all the GitHub organizations you need to publish modules from.
  • Check your module list to see if any has a warning about not being automatically synced.
  • If you still need to setup sync on some modules, try triggering a manual account sync to have PrestaSpirit try to set up hooks on your account again. Note that archived repositories can not be setup as they are readonly in GitHub's API.

Manual hook setup

If you do not use GitHub there is a generic endpoint you can call manually from a git post-receive hook or similar. You have to do a POST request to https://prestaspirit.org/api/update-package?username=USERNAME&apiToken=API_TOKEN with a request body looking like this: {"repository":{"url":"PACKAGIST_PACKAGE_URL"}}

You can do this using curl for example:

curl -XPOST -H'content-type:application/json' 'https://prestaspirit.org/api/update-package?username=USERNAME&apiToken=API_TOKEN' -d'{"repository":{"url":"PACKAGIST_PACKAGE_URL"}}'