Which version of Magento should I use? This will help you decide

A brief guideline that will help you to choose which version of Magento to use and if you’re on V1 identify if it’s a good idea to migrate your current store to V2.

Overview

Magento is one of the most widely used eCommerce platform today. It has two major versions: 1.x and 2.x. You find yourself asking the question: which one should I choose?

Image from Alan Kent’s slideshare

This would be easy to answer when you’re starting a new project: pick the one with the latest version. But what do you do with an active Magento 1 project? You should ask yourself the question of..  Do you migrate or not?

In this post I will try to bring a guideline that will help with this decision process.

Why should I migrate to Magento 2?

Unfortunately, there is no simple answer to this question as there are list of advantages and disadvantages for both versions. However, I will provide a list of pros and cons that will help you to select the best option for the project you work on.

Pros and cons

Let’s start with advantages of Magento 2

  • The Backend Admin is Designed for Non-Technical Users

The new default theme, “Luma”, provides an eye-catching theme that is drastically improved compared to the previous “Madison Island” theme.

 

  • Improved flexibility

The new platform structure has improved flexibility which consists of high code coupling, enabling developers to create complex features such as checkout, SMS, CRM, and sales.

  • Better code underneath the hood with real unit testing

With a completely overhauled codebase, created with reliable composer packages, the entire application is now covered by unit tests. This greatly improves stability and should put your mind at ease when upgrading.

  • Integrates with Popular Payment Gateways

Magento 2 is able to integrate with many of the popular payment processors, such as PayPalWorldPay, and Cybersource.

  • It is user-friendly

The Magento 2 checkout process is better streamlined, making it easier and quicker for customers to navigate through from the cart to the completed order than Magento 1. The customizable checkout now requires less customer information and steps, therefore it reduces the checkout time, increases sale conversions and minimizes abandoned carts.

  • Improved scalability and performance

Studies have shown that a one-second delay in page load time can result in a 7% loss in sales conversions. Magneto 2 runs approximately 20% faster than Magento 1, which can lead to improved SEO and increased sales. All of the content from a static page can be cached, thus increasing site performance and drastically reducing the server load. This makes the Magento 2 platform more scalable for large eCommerce stores.

But there’s still some disadvantages

  • Magento 1 themes can’t be ported

Magento 1 themes cannot be transferred to Magento 2, it will need to be built from scratch, making it an expensive endeavor.

  • Not All Extensions Are Available Yet

Unfortunately if you are already using extensions for Magento 1, unfortunately, you cannot port them into Magento 2. You’ll need to purchase the extensions and integrate them into your Magento 2 platform, also add to your overall costs.

  • Enterprise Edition Cost Rises

Although Magneto Community Edition (CE) remains free, for the Enterprise Edition (EE) a single license has increased in price from $18,000 to $22,000 per year.

  • It still has A Steep Learning Curve

All that flexibility comes at a cost, and the cost is time. You can manipulate the platform to your heart’s content, but getting over that steep learning curve is already going to be a big obstacle for any developer already unfamiliar with Magento and how it works.

  • … and hosting it can still be tricky

Dedicated file servers that can be configured to Magento’s hosting requirements absolutely must be employed, adds to the true cost of using Magento.

How to migrate

Have you decided to migrate from Magento 1 to Magento 2?

Based on Magento official documentation,  a best practice to perform migration consist in two main steps:

  1. Build and test new Magento 2
  2. Migrate four components: data, extensions, themes, and customizations.

Step 1: Build and test Magento 2

To prepare for the migration, make sure you do all of the following:

  • Set up a Magento 2.0 system using a topology and design that matches your existing Magento 1 system
  • Provide back-up of your Magento 1.x database in case of unexpected issues. We advise you to replicate your Magento 1.x database and use this Magento 1.x data for your migration
  • Install Magento 2 on a system that meets our system requirements

Next steps

Follow the links below to learn more about each of the four components.

  • Theme Migration: Since themes cannot be migrated directly, there are two options provided by official documentation: you can pick an existing theme or work with a front-end developer to create a new theme based on your current theme.
  • Extension Migration: Most of third party extensions providers offer to updated version of the product. In case you want to migrate an extension created by yourself, just refer the next paragraph.
  • Customizations Migration: Most of the code wrote for Magento 1 is compatible with Magento 2, but for those customizations that need a migration, Magento provides a Code Migration Toolkit.
  • Data Migration: Data Migration allows you to migrate several types of data from your Magento 1 store to Magento 2 store. There is a CLI tool that will help you with the process, Data Migration Tool.

Conclusion

As I mentioned above, there is no right answer in choosing between the two versions of Magento as there are advantages and disadvantages to each Magento. If you are about to start a new project, I strongly encourage you to pick the latest, it is optimized to be used with PHP 7 + and nginx server and you will be able to enjoy the goodies of this product. And if you already has a Magento 1 store, sooner than later you will have to move forward, my advise is prepare a good plan for migration and go ahead, you always can outsource this process to an agency like Arroyo Labs.

I’m glad you’re still here! Thank you for reading this post. Please leave us with questions and feedbacks if there are any! Our future post will be about an example of extension migration.

Introducing Erdiko User Admin v1

We are extremely excited to announce the first stable release of our Erdiko User Admin project. Find out more about how this open source project can help with your next web application or SPA. Contributions welcome!

We are extremely excited to announce the first stable release of our Erdiko User Admin project! After some hard work, we have a robust backend with an attractive UI to allow you to easily manage a set of roles and users you can host yourself!

We have strived to create a modular and complete solution for managing a persistent set of user records with an attractive and extendable UI.

Project Overview

The Erdiko User Admin is an Erdiko based application that provides a backend for, and serves, a custom AngularJS application. This Angular Application provides an attractive UX to help view and manage the user records we store in a database.
Here are some screenshots to give you a basic idea of the UX:

Login & User Authorization

Only authorized user’s can use the application, and we provide an simple (and attractive) login form allowing a user to input their user credentials.
Any user who is not logged in will be redirected to this form.

Home

This view is the “landing” page for a logged in user. It displays some links to our other features, but mainly it’s the default page for authorized users.

User List

The user list is a page that displays a sortable and paginated list of users in our database. This screen allows you to select a user to edit or delete.

Create User

This page shows a form allowing you to create new user.

Edit User

This page, actually the same code as the Create User, allows you to edit an existing user. This page will become more powerful as we add features in the future.

User Event Log

This page shows a paginated and sortable list of user events logged by the system. This page too will become more powerful as we add features and more options on the data we log as we continue to develop this project.

Erdiko User Admin Modules & Packages

In case you were interested in how this whole project works and some of the underlying code, we’ll give a brief overview of the modules that we used to create this project.

We have worked hard to make this package easily extendible and customizable. While the User Admin uses all of these packages at once, you can extend or replace many of these packages for your own uses.

If you are looking for more in depth information about these packages, or how you can use these packages in your custom project, please refer to their respective documentations.

erdiko/authenticate

The erdiko/authenticate package provides an authentication interface that allows us to verify a user’s provided credentials and log a user in and out. We use this to make sure you are who you say you are after logging in.
We have designed this package specifically to be flexible and extendable. If you would like to customize the authorization process, or even provide your own interface to verify a user’s identity, please refer to the documentation about extending this package.

erdiko/authorize

The erdiko/authorize package provides a role based system that allows users who have the permissions to log in and edit user records. This gives us a level of access and security for each action, and makes sure your data is safe.

erdiko/users

The erdiko/users is a package adding Service Models and AJAX endpoints for user management in a Erdiko application or your custom application.
This package requires both the erdiko/authenticate and erdiko/authorize packages to make sure a user is ‘allowed’ to interact with user records based on a requested action.

erdiko/user-admin

The erdiko/user-admin is a Erdiko MVC application that we have created in order to provide routing for our erdiko/users AJAX routes and to serve the AngularJS application we use for our UX.
If you would like more information about our Erdiko project to create a powerful and minimalistic MVC application, please refer to our documentation on Erdiko.org.

ngx-user-admin

The erdiko/ngx-user-admin package is our npm package that provides the routes, services and components we use in the AngularJS application. We have developed this in a way that will ease extension/customization as well as a focus on code re-use.

If you would like to extend some of this code for customization, please refer to our documentation.

What’s next?

We have some big plans for this project and you should expect to see in the near future:

  • More user roles!
  • Bulk User Editing!
  • An end-user interface & User Profiles!

How can you help?

We would love to have your help in our continued development of this project. Everything from development, testing and documentation; we welcome any and all feedback.

Trying it out

We highly suggest trying out the project yourself. This is the most effective way to evaluate a new project and we would love to get some feedback on how you feel about the application.

Quick start and installation instructions can be found at our official documentation site.

Reporting Bugs / Feature Requests

This project is very much a living and evolving one! We welcome feature requests and encourage our users to report bugs.

Feel free to create feature requests or report bugs on the User Admin repo we host on GitHub.

If you have a bug or feature request specific to a package please create the issue on the respective GitHub repo.

Pull Requests

Do you know what is causing an issue or a bug? Is there a missing feature or something you have worked on that you think would help out other users who use this project? We would love to see your code!

We encourage our developer end users to create Pull Requests from their forked repositories! Please make sure you abide by our contribution guidelines detailed in our official documentation.

 

Thanks so much for reading, we look forward to hearing some feedback on our project!

oAuth – Part 2

A practical example of oAuth integration into your system for authentication process.

Hello readers, today we will walk through a practical example about how to implement a simple login using the oAuth concepts described
in the previous post. To accomplish this goal we going to to create a new Erdiko project with three additional package that will help us to interact with Facebook API. Those packages are Erdiko-Authenticate and oauth2-client  and oauth2-facebook from The League of Extraordinary Packages. But before we can start coding we need to create a developer account and register our app.

How to register your app

This is the easy step; let’s demonstrate how to register using Facebook.
The first step is login in the developers site and sign in with a valid Facebook user. The next step is set you as Developer. To do this go to account, click on the button and follow instructions. Easy, right?
And the last step is to complete and submit this form. That’s it! Now you have registered your app to use Facebook API.

Prepare host project for the example

In this step we just need to create a new Erdiko project, for more details please refer to Erdiko

composer create erdiko/erdiko oauth_authenticate_sample

The next step is add the additional libraries.

In both cases, inside the project directory, will add new required packages

composer require erdiko/authenticate
composer require league/oauth2-client
composer require league/oauth2-facebook

setup erdiko-authenticate

Once it’s added we will need to add the config file in app/config/default/authenticate.json this is an example:

{
  "authentication": {
    "available_types": [{
      "name": "mock",
      "namespace": "erdiko_authenticate_Services",
      "classname": "Mock",
      "enabled": true
    }]
  },
  "storage": {
    "selected": "session",
    "storage_types": [{
      "name": "session",
      "namespace": "erdiko_authenticate_Services",
      "classname": "SessionStorage",
      "enabled": true
    }]
  }
}

we will revisit this file in future sections.

SETUP oAuth2 Client (from thephpleague)

This package doesn’t need a special configuration, but let’s take a look at constructor parameters we will user in our extension.

$provider = new \League\OAuth2\Client\Provider\GenericProvider([
    'clientId'                => 'demoapp',    
    'clientSecret'            => 'demopass',   
    'redirectUri'             => 'http://example.com/yourredirecturl/',
    'urlAuthorize'            => 'http://example.com/oauth2/authorize',
    'urlAccessToken'          => 'http://example.com/oauth2/token',
    'urlResourceOwnerDetails' => 'http://example.com/oauth2/resource'
]);

clientId and clientSecret, come from the dashboard of your registered app, in the picture below are App ID and App Secret.

redirectUri, is a public URL in your server where you will be redirected after oAuth server finish the authentication process (Facebook in our example)

The last three keys (urlAuthorize, urlAccessToken and urlResouceOwnerDetails) will change based on which service we are using. In the above block, we assume that the the oAuth server is placed in example.com, maybe our custom implementation.

Create new Service class

We will implements AuthenticationInterface that way we can inject it in our authenticate package thru autenticate.json config file we added previously.

In authentication section you will have to add a new entry in available_types array:

{
      "name": "oauth",
      "namespace": "app_services",
      "classname": "oAuthAuthenticator",
      "enabled": true
}

In the constructor method of this class we will create a provider instance for the client, but we will use the third package (oauth2-facebook) to simplify things:

namespace app\services;


use erdiko\authenticate\AuthenticationInterface;
use \League\OAuth2\Client\Provider\Facebook;

class oAuthAuthenticator  implements AuthenticationInterface
{
    protected $provider;

    public function __construct()
    {
        session_start();

        $this->provider = new Facebook([
            'clientId'          => '1925853064368417',
            'clientSecret'      => '55ea4c1a56ca6d1db485b954ZZZ',
            'redirectUri'       => 'https://example.com/login/setlogin',
            'graphApiVersion'   => 'v2.8',
        ]);
    }

    public function login($credentials)
    {
        if(!$this->checkLoggedUser()) {
           $authorizationUrl = $this->provider->getAuthorizationUrl();
           $_SESSION['oauth2state'] = $this->provider->getState();
           header('Location: ' . $authorizationUrl);
           return;
        }
    }

    protected function checkLoggedUser()
    {
       return (
            isset($_SESSION['code']) 
            && isset($_SESSION['oauth2state'])
       );
    }

    public function verify($credentials)
    {
       return true;
    }
}

 

As you can see in the login method, I’ve added a simplistic check for a logged user, if there’s no record in session will redirect to login popup. Now we’re delegating the authentication process to Facebook, and the result of this process will be finally handled by method getSetLogin in the login controller.

Use new service in a Login Controller

In this example we are using a Login Controller just to keep authentication logic isolated. This is a normal erdiko controller, where we will have three basic actions: getLogin – that will load a basic -authenticator and invoke the login method. This action will be loaded when you click on Login with Facebook buttons that you can find everywhere these days.

public function getLogin()
{
   $authenticator = new BasicAuthenticator(new User);
   
   $authenticator->login(array(),'oauth');
}

getSetLogin – a callback method – is responsible to manage Facebook response and storage user in SESSION.

public function getSetLogin()
{
    $authenticator = new BasicAuthenticator(new User());
    if (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {

        unset($_SESSION['oauth2state']);
        throw new \Exception('Invalid state.');
    }
    $token = $this->provider->getAccessToken('authorization_code', [
        'code' => $_GET['code']
    ]);
    try{
        $user = $this->provider->getResourceOwner($token);
        $authenticator->persistUser($user);
    } catch (\Exception $e) {
        throw new \Exception($e->getMessage());
    }
}

Finally, we have the getLogout action, that will destroy the SESSION and user won’t be longer authenticated.

public function getLogout()
{
   $authenticator = new BasicAuthenticator(new User());
   $authenticator->logout();
   \erdiko\core\helpers\FlashMessages::set("Good bye, ".$authenticator->currentUser()->getUsername(), "success");
   $this->getLogin();
}

Conclusion

It’s pretty easy to add oAuth features on your system as you can see. Delegating the authentication process to a trusted server, providing users with the ability to use existing trusted accounts is a clear win.

Hope you enjoy this small example! Thanks for reading and hope to see you in my next post!

oAuth – Part 1

OAuth 2.0 is the industry-standard protocol for authorization.

Overview

Welcome, today I will go through the oAuth protocol, some definitions and how it works. In a later post I will show an example of how easy it is to use oAuth with the Erdiko Authenticate package and php league packages.

What is oAuth?

I bet most of you have the same question. We can simply say that it is a protocol definition for authenticate and authorize third party applications to have access to certain user data, without sharing password with the third party app.
In other words, your application will have a token provided from a trusted service (let’s say Facebook, Twitter or any other commercials) once a user has authenticated. That way, you delegate the authentication process to this third-party server. Additionally, with this token you can access to some user’s information, previously granted by user, e.g. profile information.
When using this method we can store the token so our application doesn’t need to remember any extra authentication credentials, don’t need to fill profile fields every time register in a website, relay the security in a Trusted System.

OAuth 2.0

As per oAuth 2 site:
OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 supersedes the work done on the original OAuth protocol created in 2006.

The new version focus on client develop simplicity, and provides specific flows for Web, Desktop and Mobile developments.

Components

Components or oAuth Roles, are the main pieces involved in the auth flow.
  • Client
  • Resource Server
  • Authorization Server
  • Resource Owner
Now let’s break them down:
Client (The Third-Party Application)

Is the application that is attempting to get access to the user’s account. It needs to get permission from the user before it can do so.

Resource Server (The API)

This is the server or service used to access user’s information through an API.

The Authorization Server

This server presents the interface where the user approves or denies the request. In smaller implementations, this may be the same server as the API server, but larger scale deployments will often build this as a separate component.

Resource Owner (The User)

The resource owner is the person who is giving access to some portion of their account.

Protocol Flow

  1. The application requests authorization to access service resources from the user
  2. If the user authorized the request, the application receives an authorization grant
  3. The application requests an access token from the authorization server (API) by presenting authentication of its own identity, and the authorization grant
  4. If the application identity is authenticated and the authorization grant is valid, the authorization server (API) issues an access token to the application. Authorization is complete.
  5. The application requests the resource from the resource server (API) and presents the access token for authentication
  6. If the access token is valid, the resource server (API) serves the resource to the application

You can implement this abstract flow in different ways based on the target architecture: Web Application and Client Application. Where the first one could be any of common web sites that allow us to login using our Facebook or Twitter user, and the last one could be a mobile or desktop app.

In both cases, before start using oAuth, you need to register the application in the Service Provide system, that way you will obtain a client_id and client_secret. The client_secret should be kept confidential and only used between application and Service Provider.

Once you have registered your app,  the first step is to get authorization from the user.

This is usually accomplished by displaying an interface provided by the service to the user.

The version 2 provides several “grant types” for different use cases. The grant types defined are:

  • Authorization Code for apps running on a web server, browser-based and mobile apps
  • Password for logging in with a username and password
  • Client credentials for application access
  • Implicit was previously recommended for clients without a secret, but has been superseded by using the Authorization Code grant with no secret.

The first step is create a login link to redirect a user to Auth Server where will be authenticated. This link might include the callback URL (this could vary depends on server implementations, some systems require the callback URL in the app registration form). This is the URL user will be redirected to after login.

In case of success this redirect will include a Grant Code, that will be needed in the Token Exchange step.

After a succeed login, with Grant Code and Access Token the client app, will request the access token, that will be used as credential on future request.

Final thoughts

Hope this roughly overview brought up some light into the oAuth Protocol concepts. In the next episode, I will bring you a practical example of how to implement a client module with erdiko/authenticate package.

Testing a REST API with Frisby.js

When our web app depends on pulling data through a REST API, we need to test that the endpoints well. Thats where things become more complicated and tedious to do manually. Two great libraries, Jasmine.js and Frisby.js, can help us out here.

What is Frisby and how does it work?

We are software developers and we strive to write good code.  We try to ensure the quality of every line and workflow which in turn means testing.  Manual testing works to a point but without automated testing of REST APIs and Ajax endpoint regression testing becomes cumbersome.  Are you really going to test all the possibilities/permutations with Postman?  I didn’t think so.

Testing a REST API is not so different to testing modules, but to create “end-to-end” test cases we needed make real endpoints calls. A manual testing job quickly becomes a tedious task, so we need to find a way to make things automated.

Frisby is a REST testing framework built on node.js and jasmine, and makes testing API endpoints a very flexible and easy task.

As any normal npm package running in node, Frisby needs node.js installed first, after that you can install Frisby as a common package:

npm install -g frisby

By convention, the file name containing the Test Suite, should include the trailing word “_spec.js”, node.js runs in javascript so logically js is the extension.

In order to continue our intrduction we will study the roleAPI_spec.js, a test suite part of the package Users of Erdiko Framework:

var frisby = require('../node_modules/frisby/lib/frisby');

This is the “kickoff” for our test suite, we instance the library in a Frisby variable, it will be our object to along  the suite.

describe('Role api test suite', function() {
  var baseURL = 'http://docker.local:8088/ajax/users/roles/';
  /**---This case test the api response and check the result----*/

  frisby.create('Get all roles')
        .get(baseURL + 'roles')
        .expectStatus(200)
        .expectHeader('Content-Type', 'application/json')
        .afterJSON(function (response) {          
            expect(response.body.method).toBe('roles');
            expect(response.body.success).toBe(true);          
            expect(response.errors).toBe(false);
            expect(response.body.roles).toBeDefined();
        })     
        .toss()
});

All  Frisby test starts with frisby.create(‘A gently worded description of test’) and next we must specify the verb to make the call to our endpoint. It is obvious but must match with the endpoint structure.

In our case we used .get(baseURL + ‘roles’)

Differences between using post or get.

There are differences between verbs post and get. When we create post test cases, we should pass objects as arguments, let’s see an example grabbed from userAPI_spec.js from Users package of Erdiko framework:

/*---------------------------------------------------------*/
/*-----------------Create User success --------------------*/
frisby.create('Creation will success.')
 .post(baseURL + 'register',
 {"name":"NameTest",
  "email":"test@email.com",
  "password":"secret"},
 { json: true },
 post_header)
 .expectStatus(200)
 .toss()

By default, Frisby sends POST and PUT requests as application/x-www-form-urlencoded parameters. If we want to send a raw request content, we must use { json: true } as the third argument to the .post().

Using Expectations.

/**--checking creation with expectations --*/
frisby.create('Checking user created exist.')
    .get(baseURL + 'retrieve?id=' + USER_ID)
    .expectStatus(200)
    .afterJSON(function (response) {
        expect(response.body.method).toBe('retrieve');
        expect(response.body.success).toBe(true);
        expect(response.body.user.id).toBe(response.body.user.id);
        expect(response.body.user.email).toBe(newUser.email);
        expect(response.body.user.name).toBe(newUser.name);
        expect(response.body.user.role.id).toBe(newUser.role);
    })
   .toss()

In comparison with our traditional phpunit, the framework to create unit test cases in php, we could say that phpunit Asserts are analog to Frisby Expectations. In particular, we are interested by that expectations to handle json code. Because that we are use the ‘expect’ clause that compare the API response with a parameter provided by us:

expect(response.body.method).toBe('retrieve')

Here we expect that ‘response.body.method’ be equals to the string ‘retrieve’. It’s important to mention that the comparison is by type and value at same time and both should match to result ‘true’.

After explain that we have a few expectations used:

  • expectJSON( [path], json )
  • expectJSONTypes( [path], json )

Managing Headers, afterJSON()

/**-----------delete user created ----------------*/
frisby.create('removing user created.')
    .get(baseURL + 'cancel?id=' + USER_ID)
    .expectStatus(200)
    .afterJSON(function (response) {
        expect(response.body.method).toBe('cancel');
        expect(response.body.success).toBe(true);
        expect(response.body.user.id).toBe(USER_ID);
    })
   .toss()

As we said previously, Frisby is an extension of Jasmine.node, and afterJSON is a very good evidence because afterJSON is the extension of after() with the convenience of parse the body obtained as response as JSON values automatically. The ‘after’ occurs immediately after the response is sent from the endpoint call and is used as a callback.

Using inspectors, inspectJSON()

Inspector helpers are useful for viewing details about the HTTP response when the test does not pass, or has trouble for some reason. They are also useful for debugging the API itself as a more user-friendly alternative to curl.

// Console output
{ url: 'http://theurl/get?foo=bar',
    headers:
    { 'Content-Length': '',
        'X-Forwarded-Port': '80',
        Connection: 'keep-alive',
        Host: 'httphost.org',
        Cookie: '',
        'Content-Type': 'application/json' },
    args: { foo: 'bar'},
    origin: '127.0.0.1' }

Basically inspectJSON() prints the raw HTTP response, other similar and general inspectors are:

  • inspectBody()
  • inspectHeaders()
  • InspectRequest()
  • InspectStatus()

Conclusion

Frisby makes it possible to write end-to-end tests with a lot of flexible tools and the process of test a complete REST API turns fun and easy. We miss the ability to ‘serialize’ test cases as in a regular test unit framework. Given the nature of javascript its possible to chain nested test cases and mimic, in some aspect, that behaviors.

We haven’t tried Newman yet, but hope to soon.  Let us know about your Frisby (and Newman) experiences.

Introducing the Erdiko User Admin

Introducing the Erdiko User Admin Package! A user administration package built with an Erdiko powered backend and a Angular 2 frontend.

We’re excited to introduce the Erdiko User Admin! A modular package that provides an attractive UX to allow you to manage your users.

This is still very much a work in progress, but since we’re so excited, we want to let everyone know about this project (and request some help to keep us moving).

Check out our User Admin Project at this Github Repository and our Packagist entry.

Project Features

We wanted to create a modular and simple User Admin you can ‘bolt-on’ a new or existing project. We keep this as lean and mean as we could, but still providing some cool stuff to help get you started.

While this package is still very much in development, it does provide some of the following features:

  • A sortable and paginated list of user records.
  • An attractive user interface allowing the user to create, edit & delete user records
  • JWT user authentication!

Here’s some screenshots of our UX:

Installation and Setup

The User Admin package is a part of the Erdiko module ecosystem. Installable and upgradable via Composer. This makes it very simple to start a new project via this simple command.

composer create erdiko/user-admin [PROJECT NAME]

Please note that as of this time, we have not created an official release. You will need to include the minimum stability flag when you create your project:

composer create erdiko/user-admin [PROJECT NAME] --stability DEV

Package Dependencies

Here’s a brief list (and a bit of a plug) of some of the other Erdiko Packages we as a team have been developing that we use to build this project. While we use these packages for our development, we have planned to make these as modular and replaceable as we can.

Here’s the list:

  • erdiko/core
    • The base package that provides our basic routing and templating.
  • erdiko/authenticate
    • Authenticate the user’s credentials to assert they are who they say they are.
  • erdiko/authorize
    • A package that helps us enforce some user roles.
  • erdiko/users
    • Our Erdiko package that provides the backend storage and basic routes we use to interact with these models.

AngularJS 2

We utilize the great Angular CLI project to start and maintain the Angular code itself. This project was a great boon to help us get started on a well structured and maintainable Angular application.

The internal structure is “just” a simple app, but we have updated the NPM script to compile and move the resulting files to an directory accessible to the Erdiko application Home route.

NPM Run Scripts

Here is a quick list and an explanation of some of the custom NPM run commands we have for this project.

  • Start the local Angular Development server: npm run start
  • Run the unit tests: npm run test
  • Run the e2e/functional tests: npm run e2e
  • Compile and export files for end user: npm run build

Next Steps

Here’s an incomplete list of some of the next things we plan on working on, and completing, with the project in the future:

  • Jasmine Unit Tests to cover our angular code
  • KarmaJS Functional Tests to cover the entire application end-to-end
  • A basic User facing profile designed for user extension

How to Contribute

If you have an idea for a new feature, have an idea on how to improve a feature, or (gasp) you have found a bug please report this on our Github Repo Issues page.

However if you are just excited about this project, feel free to “star” this repo on Github to show your support.

We would also love to know if and how you use this module in your own projects!

To set your environment up for local development, please follow these steps:

  1. Clone your fork of the User Admin project into a local directory
  2. Clone the following packages into the same directory
  3. Copy the composer-dev.json file to composer.json
  4. Start your docker container docker-composer up --build

Conclusion

Thanks for reading about our exciting new package! Feel free to leave a comment or ask questions below, or feel free to comment on our Github Repo page!

Themes in the Erdiko Framework (Part 2)

In the first post we talked about how themes works in the Erdiko framework and covered important files to configure it. We continue with more advanced Erdiko theme topics and introduce new classes to discover more features, including layouts.

Today, I’m going to show you more concepts around themes in the Erdiko framework.  There are more concepts and classes to know and understand.

Layouts

To introduce the Layout class we need to define what is a layout: it includes the HTML for a basic web application structure in order to provide your own content. After made this clarification, we realize that a layout could be made by one, two, three or whatever number of columns.

Let’s look at the next code from Erdiko framework:

/**
 * Get two column layout example
 */
public function getTwocolumn()
{
    // Set columns directly using a layout
    $columns = array(
        'one' => $this->getView('examples/one'),
        'two' => $this->getView('examples/nested_view')
        );
    
    $this->setTitle('2 Column Layout');
    $this->setContent($this->getLayout('2column', $columns));
}

This code is an action from Example controller from code base of Erdiko framework. We can see how passing an array of views we can get a new layout built with ‘2column’ parameter. This way we instruct to Example controller what design we want to set to our application, and the final result will be something like this:

2columns

It’s important to take care about this latest parameter, it must exist as layout in the layout’s folder and the name must match exactly. Let’s recall our Erdiko folder structure:

layouts

the key method is Controller->getLayout():

 $this->setContent($this->getLayout('2column', $columns));

Under the hood, the controller delegates to a new Layout object composed of 2 views (one for each column) the call to render html code:

return  $layout->toHtml();

Pages

In order to reuse code the framework gives the chance of include html code often used, i.e. Header and Footer. This kind of content normally stay static around  the application. When we say “static” talk about structure however we also could include mustache code within the pages by using the {{ variable }} sintaxis.

Header

The header is a good example of html code that probably will not change in our web app. Erdiko framework installation provides us a nice default html code in the file:
app/themes/bootstrap/templates/pages/header.html

Something interesting to comment is the next piece of code:

<div class="navbar-collapse collapse" id="navbar-main">
  <ul class="nav navbar-nav">
    {{# menu.main }}
        <li>
            <a href="{{href}}">{{title}}</a>
        </li>
    {{/ menu.main }}
  </ul>
</div>

Ok, what is that sort of tag “menu.main”? Don’t worry just let’s say that we can create a html menu programmatically. When we talk about “Regions” will expand a better explanation. One important thing to highlight: the menu is built from the key “menu” in application.json file.

Footer

Footer section is more or less the same concept we talked previously with “header” but applied to the footer of application. Erdiko framework provides a default footer, the big difference against Header is the region used:

<div class="col-lg-12">
        <ul class="list-inline">
            <li class="pull-right"><a href="#top">Back to top</a></li>
            {{# menu.footer}}
                <li><a href="{{href}}">{{title}}</a></li>
            {{/ menu.footer}}
        </ul>
        <p>{{site.copyright}} {{site.full_name}}<br />
           Powered by <a href="https://github.com/ArroyoLabs/erdiko"
                         target="_blank">Erdiko</a>
        </p>
</div>

This time, the region used is ‘main.footer’ and the key used from application.json is “menu.footer”.

FlashMessages

To conclude with pages, another great and useful example is FlashMessages that provides (and being redundant) a flash message on top of the header page and denotes something important to show to the user application.

Unlike Header and Footer, FlashMessages is a helper, and you can call it:

<?php $messages = \erdiko\core\helpers\FlashMessages::get() ?>

‘$messages’ is an array and you are able to loop around it in order to give html structure:

<?php foreach($messages as $message): ?>
   <div class="alert alert-<?php echo $message['type'] ?> 
     alert-dismissible" role="alert">
     <button type="button" class="close" 
             data-dismiss="alert" aria-label="Close">
                <span aria-hidden="true">&times;</span>
    </button>
    <?php echo $message['text'] ?>
   </div>
<?php endforeach ?>

If you can get messages, it’s logic that you can set messages too 😉 :

<?php 
$message ='This is a success message to show.';
//what color we want to show the message? 'danger' is by default.
$type = 'success';
\erdiko\core\helpers\FlashMessages::set($message,$type);
?>

Regions

In the first post when we talked about Mustache we understood how a content is rendered exactly in the right position into the html code. In order to conceive Regions, we can take the same concept, regions is just a “mark” in the html code to teach the framework about what kind of html structure we want to create, just in the right position where should be placed.

Let’s take the region part of footer.html:

 {{# menu.footer}}
     <li><a href="{{href}}">{{title}}</a></li>
 {{/ menu.footer}}

When the framework process this region tag, as result we will get a nice footer created programmatically. The million dollar question is:
– How the framework makes possible to know about footer structure?
Easy, Erdiko reads the section ‘menu.footer’ and iterates the key/values within  in application.json file.

Scripts and Styles

Previously, in our post “sample application using Erdiko Framework” we proposed as example a little dice to roll with a very simple view. That view used the controller method addJs() and addCss() in order to add css and js code to the view respectively. The method signature  is the next:

/**
 * Add Css includes to the page
 *
 * @param string $name
 * @param string $file
 * @param int $order
 * @param int $active
 */
public function addJs($name, $file, $order = 10, $active = 1)
{
    $this->getResponse()
        ->getTheme()
        ->addJs($name, $file, $order,$active);
}

Both methods share the same order and number of parameters.

Views

A view object is a piece of code to provide a visual representation of model data, in object terms is a very simple class where we can modularize our html code. Let’s take an example from Erdiko framework:

$this->addView('examples/about', $data);

here we add the view ‘examples/about’ to the  controller response. The views can receive parameters, here is the constructor:

public function __construct($template = null, $data = null, $templateRootFolder = ERDIKO_APP)
{
    $this->initiate($template, $data, $templateRootFolder);
    $this->setTemplateFolder('views');
}

by reading this code we can understand easy, what kind of parameters a view needs, look how the folder ‘views’ is assigned by default.

There is no more to talk about Views, the content will be rendered by the controller with addView() method internally, calling to:

$this->appendContent($view->toHtml());

Using properties

There are a set of  properties  defined and accessibles to the entire application, we can use it between {{ variableName }} in views or templates because are just keys/values already created in application.json config. file. To mention a few of them:
– site.name
– site. description
– site.copyright

Default.php

Default.php is, paradoxically, the default template theme applied to a given view. In a general manner, default.php is a complete html page with formal sections (head, body, etc) but instead make use of static code, it call the previously defined dynamic pages as header, footer and messages. Let’s see a fragment just to understand how the sections are referenced:

<?php echo $this->getTemplateHtml('header'); ?>
<?php echo $this->getTemplateHtml('messages'); ?>
<?php echo $this->getContent(); ?>
<?php echo $this->getTemplateHtml('footer'); ?>

where the method call:

$this->getContent()

what we want is to render the View code itself.

Conclusion

Erdiko framework provides a very flexible solution to easily change the aspect of a complete web application as complex as we propose it, the key to achieve that is setup properly all our config. files and templates.
Thanks for reading!

Dependency Injection

Dependency Injection is a widely used design pattern. We will define the concepts of this pattern and show a popular PHP implementation with a simple example.

What is DI?

Dependency Injection is a software design pattern that implements Inversion of control by decoupling software modules, introduced by Martin Fowler.

Usually a dependency injection container is used to manage and automate the construction and lifetimes of interdependent objects.

di_uml

Design pattern explanation and Use

Basically, if your class needs an object of other class, in this pattern you pass the dependency object as a constructor parameter or via property setters, instead of invoke factory or create dependency. You make it someone else’s problem.
Example 1:
class MyClass {
    private $objectA;
    public function __construct(ObjectA $object) {
        $this->objectA = $object;
    }
}
Example 2:
class MyClass {
    private $objectA;

    public function setObjectA(ObjectA $object) {
        $this->objectA = $object;
    }
}

In both examples, we don’t care how or where to create the objectA we just use it.

Some popular PHP DI-Container implementations

  • PHP-DI: is an interesting implementation of DI Container that has integration with several frameworks and IDEs like PHPStorm.
  • Symfony DependencyInjection: The DependencyInjection component allows you to standardize and centralize the way objects are constructed in your application.
  • Zend – DI: DI Container implementation for Zend framwork.
  • Pimple: Is a Dependency Injection Container from SensioLabs.

Pimple Presentation

This is an implementation from SensioLabs, and you guessed it, the same guys that created the Symfony libraries.

This is a friendly implemented package, lightweight and easy to use.
To install you just need to add to your composer.json,
$ ./composer.phar require pimple/pimple ~3.0
and you’re ready to use it!
$container = new \Pimple\Container();
Since it implements \ArrayAccess interface, you can store variables and factories as it was an array.
example of parameters:
$container['cookie_name'] = 'SESSION_ID';
an example of factory as a closure:
$container['session'] = $container->factory(function($c) {
    return new Session($c['session_storage']);
});
It also provides methods to protect parameters, modify services after defined, extends, and more.
For more info refer to Pimple site.

Example Use Cases

Let’s imagine that we want to create factories dynamically based on a JSON configuration like this:
auth_config1
Then we can create a Trait with a method that will fill our container based on an argument that could be an array create from the decode of above JSON.
traits_builder
Here’s how we can use this trait:
di_using
Let’s break down the example above:
the class that implements the __construct method has defined a member attribute, container, that is an instance of Pimple.
Since we are using traits to buildAuthenticator, the result of the foreach block will be assigned into the class container attribute.
Within the build, we need to create a new temporary Pimple object. This is a hack I found to store nested containers.
This is needed because otherwise each time you attempt to add a sub-item within the “AUTHENTICATION” it overrides the previous one.
So once we have created all factories, we just set the temporal container in “AUTHENTICATION” cell of the main container.
To use your created object in the container you just need to do something like that:
$auth = $this->container["AUTHENTICATION"]["mock"];
$result = $auth->doSomething();

Final Thoughts

This pattern is very useful and widely used these days especially in modern web development, in particular if you see it used in the Angular framework.
Even when you should pick the product that better match your requirements in each case, I can say that I feel very comfortable with Pimple. As I showed, it is very flexible, allowing you to create your own wrap class to customize its behavior and fit your needs.
Hope you enjoyed! Thanks for reading and see you on next posts!

Themes in the Erdiko Framework (Part 1)

As web applications and sites become more complex it becomes important to organize your view layers with themes. We explain how to leverage the Erdiko theming engine and how to keep your code tidy and consistent. This is the first of a series of posts about Erdiko theming.

Why do we need themes?

Typically when we start a new web project, we are focused on the workflow and technical details about how the applications will work and what solution will provide to the end user. At some point of the planning process, we should start thinking about how our application will look, what data will offer, and then we begin to define our needs:

  • What is dynamic and what is static
  • What will be changed according our business logic
  • What is the menu, header, footer etc

Most of the time the HTML code will deliver rendered data elements, but half the battle of frameworks is deciding how to organize your code.

remember that design patterns are tools that you can use to solve specific problems , In MVC the Controller is responsible for determining which View is displayed in response to any action including when the application loads, if some parts of the view are very similar probably you need themes, don’t reinvent the wheel!

Currently we can find this behavior in any web application or SPA :

  • The header and footer are consistent across pages
  • The content changes according to the link we click in the navbar
  • The navbar (below the header or left aligned) will probably change according  to user level (admin, operator, visitor, etc).

At the end of the day we can realize that we don’t have to repeat over and over the same code, and we want to promote the re-usability of our code.

Thankfully, much of this work has been solved by many modern frameworks (re-inventing this is not an easy task). Let’s examine how we accomplish this with the Erdiko theming engine.

Paths and files

Let’s discuss what is in our Erdiko folder structure:

paths

For the moment just keep focusing on the “themes” folder and their nested folders. There are a lot of files right? Don’t worry let me explain:

  • themes: where each different theme is stored.
  • bootstrap: the default Erdiko’s theme.
  • views: This is where we put our HTML templates, where we render the data from our models.

Within the bootstrap theme:

  •  templates/layouts: we got templates in the most common variety: 1, 2, 3 columns and a menu.
  • templates/page: this part is the easier to understand, footer and header content, a messages file to show flash message alerts, and two special files: ‘google_header’ and ‘google_body’.  These last two allow us to insert Google Tag Manager and Google Analytics information.
  • theme.json: this file is one of the most important in order to use themes feature. Here we can set up all the previous files we talk, using json format.
  • app/config/{context}/default.json: another important config file to set up what theme will be used by the Erdiko application (theme, namespace, how many columns? And the home url). In order to demonstrate the flexibility of Erdiko framework, you can define many different contexts for a web application (default, production, etc).
  •  Default.php: the backbone file for Erdiko’s themes, here we give the main html5 structure to the final app  and also (and most important) we make use of the previous dynamic files (header, footer, example) calling the method:
Theme::getTemplateHtml().

In the same way we can show the dynamic code corresponding to the footer:

$this->getTemplateHtml('footer');

 We finally don’t know how this magic happens, how to mix dynamic data and html code in the exactly and specific parts. Is a dirty job but somebody has to do it… and the candidate is Mustache!

But what is mustache?

Mustache is a logic-less templating language that can be used to take most of the work out of creating re-usable HTML templates.

Let’s see a little example:
1. define the mustache template:

<h1>{{header}}</h1>

Please note the ‘header’ word between curly brackets.

2. define the model to user over that template:

{ "header": "Hello world!"}

3. Apply that model to the template and render it:

<h1>Hello world!</h1>

This pattern is extremely useful. Not just for re-use, but making debugging far easier.

Currently Mustache offers a lot of useful functionality but this is the most basic and important one. What we got here is the idea how it works, but remember that Mustache is One of many template systems, and the framework is not limited to use it.

Themes

The Theme class is the key element here, we need to understand how it works, their methods names are self-exaplanatory, the most important task is to process data and html templates to obtain a final html code. When a controller is created, a theme attribute is built in order to provide structure to the application. All necessary parts before to render are prepared by the _before() hook:

public function prepareTheme()
{
    $this->getResponse()
         ->setTheme(new \erdiko\core\Theme($this->getThemeName()));
}

Each time we call an action on a controller (except the ajax controllers) we automatically are setting a Theme, by inheriting the class \erdiko\core\Controller. When the action is done, tipically we create a new view passing a data array as second parameter:

$this->addView('examples/list', $data);

Or maybe we don’t want to show a view, we can just show a basic content with controller::setContent() method:

// Entering raw text on the page
$this->setContent("
    <div class=\"container\"><p>
    This is the simplest page possible.</p>
    </div>");

Then if the action is finished, the internal Theme will render their html stored. The most important methods of class Theme are:

  • addMeta(): Manages metadata of the application.
  • setPageTitle() and setBodyTitle(): Manages the title.
  • getCss() and getJs(): their setters add units of code, but the getters retrieves an array of that specific nature (array of css, or array of js stored). The result is a well formed <link> tag according to each array cell.
  • getTemplateHtml($aPartialToBeRendered): we can switch the template for a theme to render html with data.
  • toHtml(): finally we got html rendered.

In this first half of our blog post, we offer a big picture view of how theming works in Erdiko framework. At this point, we know that Controllers ‘under the hood’ already has prepared a theme ready to use with our defined content, and these themes are able of make html code. But they are not the only actors in this movie and the render concept needs to be explained a little more in depth. The next post we will continue talking about themes and discovering more actors and abilities. Thanks for reading!

User Auth… What does it really mean?

Auth, a widely use term that can be a bit confused. We will show the meaning and how to work with both definitions as a system.

Auth, a term we can see every where these days. But, what does it really mean?
Honestly, it can be confusing when just saying Auth. Are you talking about authorization or authenticating?
More over, which is the difference between those two terms? Yeah, you got the point!

So now that I have your attention, let’s start by explaining what each is and how they are different and then how we can use both in our systems.

Difference between Authenticate and Authorize

We can roughly say, in the context of computer systems, authenticate is the process that ensures and confirms a user’s identity.

In other hand we can say that authorize or authorization, is the process responsible to determine the level of access that a user has in relation with a resource.

As you may already guessed, both of these should work together as a team.

That’s cool, but how to do that?

Let’s start with Authentication

Okay, starting from a very basic example, where you need to present two keys to the system, for example, username and password, where the first one will identify you and should be unique all system wide, and the other one would confirm that you are who you said you are.

Nowadays there are other architectures that requires multi-level security layers, tokens like oAuth, and so on, but I won’t go deeper on those in this post since this is just an overview.

So, going back to the previous example, you can tackle it at different level. That means, you can go with Sysadmins and request to keep .htaccess and .htpasswd files up to date, or you can choose to tackle at application level.

As you may guess, we will discuss the last one, programmatically. Here, again, we have a bunch of alternatives based on languages, patterns, etc.

My first thought when I had to work on that was, “why should I choose one? why not define an structure that let users select and implement the most appropriate for  each project?”
Yeah, sounds great, but how can I accomplish it? Well, actually is not a big deal (unless you’re trying to reinvent the wheel), is just take a look at already implemented things. The Database layer was my inspiration.

Let me explain how so. I’ve started defining a minimal interface that any Authenticator class should implement, that way I ensure that my controllers will not be broken when I change the configuration.

iauth

As a second step, I’ve added another two interfaces, one that defines requires method to store and retrieve “session” record of current user, and the other that ensure we have at least a “login” method.

storage_interface

Finally, I mixed all this stuff in a basic atuhenticator class, that with the use of Dependency Injection pattern (Pimple in my case) allow us to load based on a config file, any authenticator class that implements our interfaces. That means, I can choose to authenticate against a plain text file, database record or oAuth server like Facebook or Twitter, I just need to implement the logic for the selected service and put it in a config file.

mock_auth

And what about Authorization?

The good news is there’s a lot of alternatives. The bad news is that most of then are not implemented for all languages, instead, it seems that each programming language pick one and discard the other.

Don’t worry, most of them can be categorized in one of those big groups:

  • Role-based access control

from wikipedia

In computer systems security, role-based access control (RBAC) is an approach to restricting system access to authorized users. It is used by the majority of enterprises with more than 500 employees, and can implement mandatory access control (MAC) or discretionary access control (DAC). RBAC is sometimes referred to as role-based security.

Role-based-access-control (RBAC) is a policy neutral access control mechanism defined around roles and privileges.

  • Access Level Control

from wikipedia

An access control list (ACL), with respect to a computer file system, is a list of permissions attached to an object. An ACL specifies which users or system processes are granted access to objects, as well as what operations are allowed on given objects. Each entry in a typical ACL specifies a subject and an operation. For instance, if a file object has an ACL that contains (Alice: read,write; Bob: read), this would give Alice permission to read and write the file and Bob to only read it.

  • Identity Management

from wikipedia

In computer security, identity and access management (IAM) is the security and business discipline that “enables the right individuals to access the right resources at the right times and for the right reasons”. It addresses the need to ensure appropriate access to resources across increasingly heterogeneous technology environments and to meet increasingly rigorous compliance requirements.

In my case, I based on Ruby On Rails’ CanCan gem. Is very nice the way they implemented the “ability” class to grant users and groups the access to specific resource.
This time I’ve based on AC\Kilinka (compose package from American Council) and basically extended it to cover my needs.
Let’s breakdown a bit to make things more clear, there are two big parts, Authorizer and Guard, and two interface that defines them.
The first one, GuardInterface define four basic methods that will be responsible for get and check policies related with an specific resource, the other one, AuthorizerInterface, has two method, one for register guards and “can”, that decides if an action on a resource is permitted.
kalinka_guardinterface
kalinka_authorizerinterface

 

This package also provides some basic implementations. I’ve chosen RoleAuthorizer that better match to my needs, because users used to have a role associated. However, you can use a SimpleAuthorizer that allows you to allow/deny access by user instead of group.

The main difference is the way you config your permissions, here’s an example of what I did in a JSON format:
auth_json

Final thoughts

I have presented a brief overview about how you can identify users and manage permissions to your app resources.
Hope you enjoyed, thanks for reading, and stay tuned in this blog because we will bring you a new Erdiko packages that implements those things, soon!