Repository files navigation

• https://matomo.org
• https://developer.matomo.org

• Index
• Classes
• Namespaces
• Hooks
• Guides

Copyright Matomo team. Do not republish, or copy, or distribute this code or content. Thank you!

$cd app/$ php -r"copy('https://getcomposer.org/installer', 'composer-setup.php');"$ php -r"if (hash_file('sha384', 'composer-setup.php') === '906a84df04cea2aa72f40b5f787e49f22d4c2f19492ac310e8cba5b96ac8b64115ac402c8cd292b8a03482574915d1a8') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"$ php composer-setup.php$ php -r"unlink('composer-setup.php');"$ composer install$ mkdir tmp/cache$ mkdir tmp/templates$cd public/$ php -S 0.0.0.0:8000

To disable caching and enable debugging, create aapp/config/local.php file with the following:

<?phpdefine('CACHING_ENABLED',false);define('DEBUG',true);

Without cache, the website might be slow because of the inclusion of remote files (through HTTP). You can disable thatlocally by adding this to yourlocal.php:

define('DISABLE_INCLUDE',true);

# Clone Matomo repository the first timegit clone git@github.com:matomo-org/piwik.git piwik# Download the dependencies for our generator cd generator/composer installcd ../piwik/# Now set up composer according to https://getcomposer.org/download/

• Execute./generate.sh
• Commit
• Push

or just execute./generateAndPush.sh.

The documents will be generated into thedocs/generated directory. It will always generate the documentation for the latest stable version.

• Increase version number forLATEST_PIWIK_DOCS_VERSION inconfig/app.php
• Copy the previous documentation folder to the new one egcp docs/4.x docs/5.x -R
• Add a new line togenerate.sh eggenerateDocs "4.x-dev" "4.x" similar to the other ones. You might also want to copy the generation success detection.
• Copy pictures from the previous version into latest version eg frompublic/img/3.x topublic/img/4.x and update all needed pictures.
• Inapp/routes/page.php we might need to update the branch for the latestCHANGELOG version in the/changelog routesee eghttps://github.com/matomo-org/developer-documentation/blob/0.1.0/app/routes/page.php#L156 . It will be important thatwe merge all changes to the changelog for different Matomo versions into the changelog of the latest Matomo version as we currentlywant to show one changelog across all versions.

So far, docs can be put intodocs/2.x,docs/3.x and directly underdocs/. If eg a guide is requested for Piwik 2,we first look for docs indocs/2.x and if not found for docs indocs/. This allows us to have some pages always thesame, eg "Support" page, "Matomo Core Development", etc. So far I have left all guides underdocs/ as not many docs willactually change for Matomo 3. This way, when changing a document underdocs/ it will be updated for Piwik 2 and Matomo 3.

As soon as something on a guide changes for Matomo 3, we should copy that article into docs/2.x and afterwards makeadjustments on the content for Matomo 3.

If a guide will be removed for a newer Matomo version and does not exist in the latest Matomo version anymore we should setupa redirect inapp/helpers/Redirects.php eg to redirect/guides/pages to/2.x/guides/pages. This can be optional asthe 404 Error page would suggest to open that page.

• When an article references a resource / URL that is not available for another Matomo version. For example an article linksto the API reference guide to a class that is not available in another Matomo version
• When links for some reason are not the same for 2 different Matomo versions in general
• When an article references eg menu items or something else but it is not the same across Matomo versions. For examplethere is no user menu in Matomo 3 anymore, or Plugin Settings are now split into "Personal Settings" and "General Settings". In sucha case we need to make a copy of that article as the guide would be wrong otherwise.
• When a submenu is different across Matomo versions. Submenus are usually defined in markdown files, for example under"Develop => Plugin Basics" submenu items are defined indevelop-plugin-basics.md. If we eg add a new Import API into Matomo X wewould need to create that new guide under/docs so it will be also available for Matomo 4 etc and then copy/docs/develop-plugin-basics.md into/docs/2.x/develop-plugin-basics.md and next add the menu item to/docs/develop-plugin-basics.md.
• There can be many more reasons. In general if articles are different between 2 versions for various reasons because they mentioneg outdated classes, outdated configs etc or when links break between 2 Matomo versions etc we need to created a copy of thatguide, put it into egdocs/2.x and then update the existing article under/docs.

Images are always stored in a versioned directory. Egpublic/img/2.x/* andpublic/img/3.x/*. When there is a new Matomo versionwe need to copy all the images from the previous version and put them into a new Matomo directory. In guides you would stillreference an image via/img/myimage.jpg and the Markdown parser will add the path for the currently selected Matomo version andturn it into either eg/img/2.x/myimage.jpg or/img/3.x/myimage.jpg. With a new Matomo version often the UI changes and this wayit keeps things simple by having always different images and by not using the same image across different Matomo versions.

Just edit thedocs/*.md files. Any change you make there should be available on the developer website within a minute.

Guides are written using Markdown.CommonMark andMarkdown Extra are supported.

In addition:

• headers have an autogenerated HTML ID (so that they can be linked to). You can also use Markdown Extra to explicitly define it:## Some title {#some-title-id}
• you can include remote files as-is using:
  • {@include http://example.com/file.xml}: the content isnot escaped
  • {@include escape http://example.com/file.xml}: the content will be escaped

Create a new Markdown file indocs/ and use YAML Front Matter to configure it:

---category:Develop---#The titleLorem ipsum…

YAML Front Matter is YAML embedded at the top of Markdown files. It is commonly used to define metadata, and we use it to define several items:

• category: the name of the category (Develop, Integrate, Design, API Reference)
• subGuides: allows you to define a list of sub-guides (will appear in the left sidebar)
• previous: allows you to define the previous guide (a link will be added at the end of the guide, it does not affect the sidebar)
• next: allows you to define the next guide (a link will be added at the end of the guide, it does not affect the sidebar)

A guide must be either added to a category menu or set as a "sub-guide" of another guide. It cannot be both (else it will appear twice in the left sidebar).

To add a guide to a category (i.e. it will appear in the left sidebar) edit the PHP class for the category (inapp/helpers/Content/Category).

Some menu items need to be added by adding the markdown filename without the.md in one of thesecategory classes.

Some submenu items need to be added as a subguidesee for example this example.

It really depends submenu item which one you need to edit. If the parent menu item defines it's submenu items in a category class, then you need a new entry there. Otherwise you need to edit the markdown file for the parent menu item and add a new entry tosubGuides.

Please note that also thecategory: in the beginning of your guide needs to match the name of the category this page should be in. The category name can be for exampleDevelop,DevelopInDepth,Integrate orAPI Reference.

The following tags can be used in PHP docblocks so that they can be turned to links in the API reference.

{@hook Request.dispatch}                    // link to Request.dispatch hook{@hook Request.dispatch description text}   // link to Request.dispatch hook with different link text{@hook # description}                       // link to hooks page

Note: In contrast to @link we do not check whether a hook with the given name exists.

{@link Map}                  // class within this namespace{@link Piwik\DataTable\Map}  // full classname{@link \Exception}           // php internal class{@link serialize()}          // php internal function{@link getKeyName()}         // method within this class{@link $myproperty}          // property within this class{@link INDEX_NB_UNIQ_VISITORS}  // constant within this class, note: a link will be only generated if the constant has a long description{@link Map::getKeyName()}    // method from any class{@link Map::$myproperty}     // property from any class{@link Piwik\Metrics::INDEX_NB_UNIQ_VISITORS}  // constant from any class, note: a link will be only generated if the constant has a long description{@link http://matomo.org}    // http link{@link https://matomo.org}   // https link{@link mailto:test}          // mailto link{@link Map Description Text}                  // class within this namespace{@link Piwik\DataTable\Map Description Text}  // full classname{@link \Exception Description Text}           // php internal class{@link getKeyName() Description Text}         // method within this class{@link $myproperty Description Text}          // property within this class{@link Map::getKeyName() Description Text}    // method from any class{@link Map::$myproperty Description Text}     // property from any class{@link http://matomo.org Description Text}    // http link{@link https://matomo.org Description Text}   // https link{@link mailto:test Description Text}          // mailto link