Download the PHP package oxid-esales/module-template without Composer

On this page you can find all versions of the php package oxid-esales/module-template. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package module-template

OXID eShop Module Template

Development Latest Version PHP Version

Quality Gate Status Coverage Technical Debt

Reusable module template for extending OXID eShop core functionality.

This module also comes with all the quality tools OXID recommends to use.

If you are looking for a module with code examples, please check out the examples-module.

Table of contents

  1. Branch compatibility
  2. The Idea
  3. Goals
  4. Install and try it out
  5. Use as a base for own module
  6. Things to be aware of
  7. Running tests and quality tools
  8. Additional info

Branch compatibility

The Idea

OXID eSales would like to provide a lightweight reusable module to be used as a template for developing own module solutions.

Goals

There are two main goals this repository is intended to help with:

Install and try it out

Note: This installation method fits for trying out the module development basics, its not meant to be used as development base for your own module. Check further installation/usage methods.

This module is in working state and can be directly installed via composer:

and activate the module.

Use as a base for own module

In case you'd like to use this module as a template for your own module, this section is for you.

Important Instructions here are for the case you intend to develop a module for OXID eShop 7.3.x. For other versions, refer to the version specific branch.

Before starting to do something, please, read the whole section once, then decide on required questions, decide what you want to achieve, and follow the procedure.

Terms

First, lets decide on terms:

In the following examples, your information required places will be shown as placeholders: <yourPackageName>, it means you should put your package name at that place, without brackets, for example:

will possibly look like:

in our case it is:

Procedure

The following procedure describes how to create a base for your further module, and shows the basic installation for the development process:

1. Use the Template

Click on the "Use this template" button on the template main page to create your module repository from the given template.

Please make sure to NOT choose the 'take all branches' option, as this will clone the repository with everything we have in our repository. Having all branches also will trigger the github actions for all branches and you dont want this usually.

As an outcome of this step, you should have a repository with one "Initial commit" of our current latest repository state.

2. Personalize and cleanup the module

To personalize the module, use the "bin/personalize.sh" script. This script will prompt you for required information and do the work.

For this step, clone your module repository anywhere to your local directory and run the desired scripts.

Also, you will need to adjust the README, CHANGELOG, LICENSE, metadata and the GitHub workflow file, with your credentials and names. For running SonarCloud as part of the steps in GitHub workflow you will need to configure SonarCloud and to create a secret environment variable for your repository called SONAR_TOKEN. The token itself is provided by SonarCloud.

3. Install the module for Development

For installing the module for development our recommended way, check the "Development installation section", or do it any other way you prefer, but make sure to reconfigure our preconfigured quality tools to fit your installation.

Development installation

We recommend developing the module as independent as possible. This means that the module for development should be installed as a root package, with its own strict dependencies if such are needed.

The next section shows how to install the module as a root package by using the OXID eShop SDK.

In case of different environment usage, please adjust by your own needs.

Development installation on OXID eShop SDK

The installation instructions below are shown for the current SDK for shop 7.3. Make sure your system meets the requirements of the SDK.

  1. Ensure all docker containers are down to avoid port conflicts

  2. Clone the SDK for the new project

  3. Clone the repository to the source directory

  4. Run the recipe to setup the development environment, you can decide which shop edition to install. Omitting the flag installs EE.

You should be able to access the shop with http://localhost.local and the admin panel with http://localhost.local/admin (credentials: [email protected] / admin)

Things to be aware of

The module template is intended to act as a skeleton module so keep your eyes open for comments in the code.

NOTES:

Module migrations

Migrations have to be run via console command (./vendor/bin/oe-eshop-doctrine_migration)

For more information, check the developer documentation.

Where the module namespace points to

As already mentioned above, in the 7.x versions of OXID eShop, the module code only resides in the vendor directory so the namespace needs to point there. In our case this looks like

Running tests and quality tools

Check the scripts section in the composer.json of the module to get more insight of preconfigured quality tools available. Example:

Integration/Acceptance tests

After this done, check the "scripts" section of module composer.json file to see how we run tests.

NOTE: From OXID eShop 7.0.x on database reset needs to be done with this command (please fill in your credentials)

And just in case you need it, admin user can now also be created via commandline

for example

Writing Codeception tests

As a rule of thumb, use codeception tests to ensure the frontend is behaving as expected. Codeception tests take a while to run, so try to navigate the way between covering the relevant cases and overtesting.

We definitely need some acceptance tests if the module affects the frontend. If the module breaks the frontend, we need to see it asap.

The great thing about codeception tests is - they can create screenshot and html output in failure case, so you literally get a picture of the fail (tests/Coreception/_output/).

Github Actions Workflow

The module template comes complete with a github actions workflow. No need to rig up some separate continuous integration infrastructure to run tests, it's all there in github. You will see three files in .github/workflow directory. The workflow from .github/workflow/trigger.yaml starts on every push and pull_request to run the code quality checks and all the module tests.

In our experience it is useful to run the shop tests with the module installed and activated from time to time. For sure those shop tests have been written with only the shop itself in mind. Your module, depending on what it is doing, might completely change the shop behaviour. Which means those shop tests with a module might just explode in your face. Which is totally fine, as long as you can always explain WHY those tests are failing.

Real life example: There is one shop acceptance test case OxidEsales\EshopCommunity\Tests\Acceptance\Frontend\ShopSetUpTest: which is testing the frontend shop setup. Very good chance this test will fail if a module is around which extends the class chain. That test is for setting up a shop from scratch so it will simply not expect a module to be around. And we only need our module to safely work with a working shop. We definitely will decide to skip that ShopSetUpTest as we have a good explanation as to why it will not work. And having this special test case work with our module will give no benefit.

This is only one example, there might be other tests that fail with your module but fail because your module is changing the shop. In that case the suggestion would be to exclude the original test from the github actions run, copy that test case to your module tests and update to work with your module. This was for example the strategy used for our reverse proxy modules which are mandatory to not make the shop's acceptance tests fail. Unless those test cases that somehow bypass reverse proxy cache invalidation. To be on the safe side, we took over those few test cases to the module and plan to improve the shop tests as soon as possible. We'll gladly also take your PR with improved shop tests ;)

And then there are some few shop tests marked as @group quarantine in the doc block. Test in that group have stability issues so they'd better be excluded as well.

Ps: a failing shop test might also turn up issues in your module, in that case fix the module and let the test live ;)

Additional info

Useful links

Contact us

In case you have any complaints, suggestions, business cases you'd like an example for please contact us. Pull request are also welcome. Every feedback we get will help us improve.

All versions of module-template with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package oxid-esales/module-template contains the following files

Loading the files please wait ....