• Building extensions for Pagekit Part #2 - First steps

Building extensions for Pagekit Part #2 - First steps

Phpstorm gitignore

Potentially outdated

This post is older than 365 days and may be outdated. Please use the site-search to search for updated information.

Hello again,

I promised to go on with my new blog series Building extensions for Pagekit - and here it is: The second part.

What we are going to do

We are going to develop an extension that will be added to Pagekit's marketplace when we are done.

The name of the extension: spqr/survey. As the name suggests: This will allow the user to add surveys to a Pagekit-based website.

We will have backend menus for the settings and for the possibility to create and edit new surveys.

Later we will also add a widget and a content plugin.

A lot to do, huh? So let's get started.

Create a Git(Hub) repository

We are going to use GitHub as a Git service. Of course you are free to use any other Git service - there are tons of good alternatives like

You can also follow this series with another version control system or without having one configured at all.

Create the repository

At first you need to create a GitHub account. You can do this for free: GitHub sign up.

After you signed up you can easily add a new repository.

Github new repository

Quite easy, huh? Now we are going to name it and add some basic information.

Github create repository

In this case, we are going to name it pagekit-surveys and add the MIT license to it. As we are going to use composer later on, we will add composer to .gitignore file.

Check out the project

Now we are going check out this repository. You can do this via CLI - but some IDEs have this feature on board already.

Using PHPStorm it's really simple: Just start PHPStorm and choose "Check out from version control" in the welcome screen. Now you can choose "GitHub" from the dropdown.

Phpstorm checkout new project

You are now asked to enter the URL of the repository. Maybe, if those information are not saved yet, you are asked to enter your GitHub login credentials.

Phpstorm github credentials

Entered all information? Then you can either click on "Test" to verify the data you just entered or proceed clicking "Clone".

You are done? Fine - now you should see the following screen:

Phpstorm checkout done

Download the Pagekit source

We would like to include the Pagekit's source in our IDE - so we need to download Pagekit from Pagekit.com and save it somewhere on our computer. Just unzip the archive and remember the path of the Pagekit's source.

If you like to you can move the sources to another directory - you just have to remember the path later.

Adjust the IDE

In the next step we will adjust our IDE.

  1. Open Preferences > Languages & Framework > PHP and choose PHP 7.2 as used PHP version
  2. Stay in Preferences > Languages & Framework > PHP and add the Pagekit source as include path. Remember? We just downloaded the source a few minutes ago.
  3. Open Preferences > Languages & Framework > JavaScript and choose ECMA script 6.

Phpstorm php settings

Phpstorm php include path

Phpstorm javascript settings

Of course you are free to adjust your IDE just as you would like to. I am going with these settings and I am fine with it.

Edit .gitignore

We are going to use composer, node.js packages and we are going to use webpack. All these tools are creating tons of files we do not really want to add to our repository.

Our IDE creates some configuration files aswell - we do definitely not add them to our public GitHub repository.

On your file's overview you may find a file called .gitignore. Doubleclick to edit it and change the content from

composer.phar
/vendor/

# Commit your application's lock file http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file
# You may choose to ignore a library lock file http://getcomposer.org/doc/02-libraries.md#lock-file
# composer.lock

Phpstorm gitignore

to

composer.phar
/vendor/
/node_modules/
.idea/
/app/bundle
/app/assets

# Commit your application's lock file http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file
# You may choose to ignore a library lock file http://getcomposer.org/doc/02-libraries.md#lock-file

Phpstorm gitignore edited

Add composer.json

At first we are going to add a file called composer.json. On PHPStorm you just need to click on the file-tree and press the keys Command + N. Now choose File and name our new file composer.json.

You should be asked whether you want to add the file to git. Of course you want to ;).

Phpstorm files overview Phpstorm add file Phpstorm filename Phpstorm add file to git

If you are using another editor or IDE you should be able to add files on a similar way.

The composer.json defines our composer package and contains some information about our extension like:

  • Name (which consists of a vendor name and the extension name)
  • Version
  • Title
  • Description
  • License
  • Author
  • Extras
  • Dependencies

In our case we will go with this content:

{
  "name": "spqr/survey",
  "module": "spqr/survey",
  "version": "0.0.1",
  "type": "pagekit-extension",
  "title": "Survey",
  "description": "Allows you to add surveys to your Pagekit-based website",
  "license": "MIT",
  "authors": [
    {
      "name": "Roman Lossin-Be├čler",
      "homepage": "https://spqr.wtf"
    }
  ],
  "extra": {
    "icon": "icon.svg",
    "scripts": "scripts.php"
  },
  "require": {
  }
}

You do not necessarily have to add this line: "module": "spqr/survey", - but it will be very useful later - so trust me and set it to the same value as your name value.

Did you mention this part?

  "extra": {
    "icon": "icon.svg",
    "scripts": "scripts.php"
  },

This adds an icon to our extension (which does not exist yet) and we are adding a script, which can perform additional tasks on

  • installation
  • update
  • remove

We will create the file scripts.php later - let's continue with the module definition.

Add module definition

Simply create a new file called index.php. This file is the entry point for our extension and contains a lot of information packed in some kind of array-structure.

<?php

return [
    'name' => 'spqr/survey',
    'type' => 'extension',
    'main' => function( Application $app ) {
    },

    'autoload' => [
        'Spqr\\Survey\\' => 'src'
    ],

    'nodes' => [],

    'routes' => [],

    'widgets' => [],

    'menu' => [],

    'permissions' => [],

    'settings' => '@survey/settings',

    'resources' => [
        'spqr/survey:' => ''
    ],

    'config' => [],

    'events' => []
];

Alright - what is this all about?

Obviously this is returning an array of information, Pagekit needs to include our new extension.

At first we define a name: 'name' => 'spqr/survey',

You do not necessarily have to prefix your name like I did - but it can be an advantage. If you would only name it 'name' => 'survey', it could be possible that another developer creates an extension called "Survey", too - and this could cause problems. So prefixing your extension is always a great idea.

Later we are telling Pagekit, whether this package is an extension or a theme: 'type' => 'extension',.

We also create an empty main function:

'main' => function( Application $app ) {
    },

You could already start coding in this main function - it would work fine, but it could be a bit confusing adding tons of code here. So we are not going to do this - but for testing reasons you could try, what happens, if you are echo some content here.

The next step is to define an autoload directory for my classes I am going to use later. These classes can be controllers, models or helpers. You have no idea what a controller is? No problem - we will come to this later.

    'autoload' => [
        'Spqr\\Survey\\' => 'src'
    ],

As we are going to have a settings-tab in our extension, I would like to link these settings in Pagekit's extension overview. So I added the route to the settings right here:

'settings' => '@survey/settings',

Well - there is no route yet, but we will come to this later.

As our extension is going to be located in pagekit/packages/spqr/survey I am going to create a little "shorthand", which I can use later to include assets.

This can be easily done with:

    'resources' => [
        'spqr/survey:' => ''
    ],

Now I can just write spqr/survey to load files like PHP-files or assets like images, scripts or style-definitions. Quite handy, isn't it?

As we do not have a module configuration or any event-based stuff, we will return empty values just like that:

    'config' => [],

    'events' => []

We will come to this later, too.

Let's have a break

This is my post for today. There are a lot of things you do not really need to understand for now - we will come to the most important things in the next "lessons".

Today we:

  • Created a Git-repository and checked it out with our IDE
  • Edited the .gitignore file
  • Adjusted the IDE
  • Created composer.json and the module definition (index.php)

Great - I can't wait to continue with my next blog post on this little blog series. Stay tuned :-).

{{ message }}

{{ 'Comments are closed.' | trans }}

Wait a second!

Did you know that there's are great support channels for Pagekit? Visit us today and sign up for free using email or your GitHub-, Twitter-, Google- or Facebook-Account.

Latest blog posts

Latest comments

  • How to fork a theme

  • spqr/toc updated

  • spqr/toc updated

Like my work?

If you would like to support my work, you are invited to do so.