Recherche avancée

Sur d’autres sites (9020)

• How to create a command – Introducing the Piwik Platform

  2 octobre 2014, par Thomas Steur — Development

  This is the next post of our blog series where we introduce the capabilities of the Piwik platform (our previous post was How to publish your plugin or theme on the Piwik Marketplace). This time you’ll learn how to create a new command. For this tutorial you will need to have basic knowledge of PHP.

  What is a command ?

  A command can execute any task on the command line. Piwik provides currently about 50 commands via the Piwik Console. These commands let you start the archiver, change the number of available custom variables, enable the developer mode, clear caches, run tests and more. You could write your own command to sync users or websites with another system for instance.

  Getting started

  In this series of posts, we assume that you have already set up your development environment. If not, visit the Piwik Developer Zone where you’ll find the tutorial Setting up Piwik.

  To summarize the things you have to do to get setup :

  • Install Piwik (for instance via git).
  • Activate the developer mode : ./console development:enable --full.
  • Generate a plugin : ./console generate:plugin --name="MyCommandPlugin". There should now be a folder plugins/MyCommandPlugin.
  • And activate the created plugin under Settings => Plugins.

  Let’s start creating a command

  We start by using the Piwik Console to create a new command. As you can see there is even a command that lets you easily create a new command :

  ./console generate:command

  The command will ask you to enter the name of the plugin the created command should belong to. I will simply use the above chosen plugin name “MyCommandPlugin”. It will ask you for a command name as well. I will use “SyncUsers” in this example. There should now be a file plugins/MyCommandPlugin/Commands/Syncusers.php which contains already an example to get you started easily :

  class Syncusers extends ConsoleCommand
  {
      protected function configure()
      {
          $this->setName('mycommandplugin:syncusers');
          $this->setDescription('MyCommandPlugin');
          $this->addOption('name', null, InputOption::VALUE_REQUIRED, 'Your name:');
      }
   
      /**
       * Execute command like: ./console mycommandplugin:syncusers --name="The Piwik Team"
       */
      protected function execute(InputInterface $input, OutputInterface $output)
      {
          $name    = $input->getOption('name');
   
          $message = sprintf('Syncusers: %s', $name);
   
          $output->writeln($message);
      }
  }
  Télécharger

  Any command that is placed in the “Commands” folder of your plugin will be available on the command line automatically. Therefore, the newly created command can now be executed via ./console mycommandplugin:syncusers --name="The Piwik Team".

  The code template explained

  protected function configure()
  {
      $this->setName('mycommandplugin:checkdatabase');
      $this->setDescription('MyCommandPlugin');
      $this->addOption('name', null, InputOption::VALUE_REQUIRED, 'Your name:');
  }
  Télécharger

  As the name says the method configure lets you configure your command. You can define the name and description of your command as well as all the options and arguments you expect when executing it.

  protected function execute(InputInterface $input, OutputInterface $output)
  {
      $name    = $input->getOption('name');
      $message = sprintf('Syncusers: %s', $name);
      $output->writeln($message);
  }
  Télécharger

  The actual task is defined in the execute method. There you can access any option or argument that was defined on the command line via $input and write anything to the console via $output argument.

  In case anything went wrong during the execution you should throw an exception to make sure the user will get a useful error message. Throwing an exception when an error occurs will make sure the command does exit with a status code different than 0 which can sometimes be important.

  Advanced features

  The Piwik Console is based on the powerful Symfony Console component. For instance you can ask a user for any interactive input, you can use different output color schemes and much more. If you are interested in learning more all those features have a look at the Symfony console website.

  How to test a command

  After you have created a command you are surely wondering how to test it. Ideally, the actual command is quite short as it acts like a controller. It should only receive the input values, execute the task by calling a method of another class and output any useful information. This allows you to easily create a unit or integration test for the classes behind the command. We will cover this topic in one of our future blog posts. Just one hint : You can use another command ./console generate:test to create a test. If you want to know how to test a command have a look at the Testing Commands documentation.

  Publishing your Plugin on the Marketplace

  In case you want to share your commands with other Piwik users you can do this by pushing your plugin to a public GitHub repository and creating a tag. Easy as that. Read more about how to distribute a plugin and best practices when publishing a plugin.

  Isn’t it easy to create a command ? We never even created a file ! If you have any feedback regarding our APIs or our guides in the Developer Zone feel free to send it to us.

• How to verify user permissions – Introducing the Piwik Platform

  9 novembre 2014, par Thomas Steur — Development

  This is the next post of our blog series where we introduce the capabilities of the Piwik platform (our previous post was How to make your plugin multilingual). This time you’ll learn how to verify user permissions. For this tutorial you will need to have basic knowledge of PHP and the Piwik platform.

  When should a plugin verify permissions ?

  Usually you want to do this before executing any action – such as deleting or fetching data – and before rendering any sensitive information that should not be accessible by everyone. For instance in an API method or Controller action. You sometimes also need to verify permissions before registering menu items or widgets.

  How does Piwik’s user management work ?

  It is quite simple as it only differentiates between a few roles : View permission, Admin permission and Super User permission. If you manage multiple websites with Piwik a user can be assigned to different roles as a user might have no permission for some websites but view or admin permission for another set of websites.

  Worth mentioning is that roles inherit from each other. This means the role admin automatically includes the role view and a super user automatically covers the view and admin role.

  Getting started

  In this post, we assume that you have already set up your development environment and created a plugin. If not, visit the Piwik Developer Zone where you’ll find the tutorial Setting up Piwik and other Guides that help you to develop a plugin.

  Verifying user permissions

  To protect your data the platform offers many convenient methods in the \Piwik\Piwik class. There you will find methods that either start with check, is or has. While methods that start with check throw an exception in case a condition is not met, the other methods return a boolean true or false.

  Use methods that throw an exception if you want to stop any further execution in case a user does not have an appropriate role. The platform will catch the exception and display an error message or ask the user to log in.

  public function deleteAllMessages()
  {
      // delete messages only if user has super user access, otherwise show an error message
      Piwik::checkUserSuperUserAccess();
   
      $this->getModel()->deleteAllMessages();
  }
  Télécharger

  Use methods that return a boolean for instance when registering menu items or widgets.

  public function configureAdminMenu(MenuAdmin $menu)
  {
      if (Piwik::hasUserSuperUserAccess()) {
          $menu->addPlatformItem('Plugins', $this->urlForDefaultAction());
      }
  }
  Télécharger

  It is important to be aware that just because the menu item won’t be displayed in the UI a user can still open the registered URL manually. Therefore you have to check for permissions in the actual controller action as well.

  View permission

  A user having a view permission should be only able to view reports but not make any changes apart from his personal settings. The methods that end with UserHasSomeViewAccess make sure a user has at least view permission for one website whereas the methods *UserHasViewAccess($idSites = array(1,2,3)) check whether a user has view access for all of the given websites.

  Piwik::checkUserHasSomeViewAccess();
   
  Piwik::checkUserHasViewAccess($idSites = array(1,2,3));
  Télécharger

  As a plugin developer you would usually use the latter example to verify the permissions for specific websites. Use the first example in case you develop something like an “All Websites Dashboard” where you only want to make sure the user has a view permission for at least one website.

  Admin permission

  A user having an admin permission cannot only view reports but also change website related settings. The methods to check for this role are similar to the ones before, just swap the term View with Admin.

  Piwik::checkUserHasSomeAdminAccess();
   
  Piwik::checkUserHasAdminAccess($idSites = array(1,2,3));
  Télécharger

  Super user permission

  A user having the super user permission is allowed to access all of the data stored in Piwik and change any settings. To check if a user has this role use one of the methods that end with UserSuperUserAccess.

  Piwik::checkUserHasSuperUserAccess();

  As a plugin developer you would check for this permission for instance in places where your plugin shows an activity log over all users or where it offers the possibility to change any system wide settings.

  Getting information about the currently logged in user

  Sometimes you might want to know which user is currently logged in. This can be useful if you want to persist user related information in the database or if you want to send an email to the currently logged in user. You can easily get this information by calling the following methods :

  $login = Piwik::getCurrentUserLogin()
  $email = Piwik::getCurrentUserEmail()
  Télécharger

  Advanced features

  Of course there is more that you can do. For instance you can verify whether a user is an anonymous user or whether a user has a specific role. You can also perform any operation in the context of a super user even if the current user does not have this role. Would you like to know more about those features ? Check out the Piwik class reference, the Security guide and the Manage Users user guide.

  If you have any feedback regarding our APIs or our guides in the Developer Zone feel free to send it to us.

• How to verify user permissions – Introducing the Piwik Platform

  9 novembre 2014, par Thomas Steur — Development

  This is the next post of our blog series where we introduce the capabilities of the Piwik platform (our previous post was How to make your plugin multilingual). This time you’ll learn how to verify user permissions. For this tutorial you will need to have basic knowledge of PHP and the Piwik platform.

  When should a plugin verify permissions ?

  Usually you want to do this before executing any action – such as deleting or fetching data – and before rendering any sensitive information that should not be accessible by everyone. For instance in an API method or Controller action. You sometimes also need to verify permissions before registering menu items or widgets.

  How does Piwik’s user management work ?

  It is quite simple as it only differentiates between a few roles : View permission, Admin permission and Super User permission. If you manage multiple websites with Piwik a user can be assigned to different roles as a user might have no permission for some websites but view or admin permission for another set of websites.

  Worth mentioning is that roles inherit from each other. This means the role admin automatically includes the role view and a super user automatically covers the view and admin role.

  Getting started

  In this post, we assume that you have already set up your development environment and created a plugin. If not, visit the Piwik Developer Zone where you’ll find the tutorial Setting up Piwik and other Guides that help you to develop a plugin.

  Verifying user permissions

  To protect your data the platform offers many convenient methods in the \Piwik\Piwik class. There you will find methods that either start with check, is or has. While methods that start with check throw an exception in case a condition is not met, the other methods return a boolean true or false.

  Use methods that throw an exception if you want to stop any further execution in case a user does not have an appropriate role. The platform will catch the exception and display an error message or ask the user to log in.

  public function deleteAllMessages()
  {
      // delete messages only if user has super user access, otherwise show an error message
      Piwik::checkUserSuperUserAccess();
   
      $this->getModel()->deleteAllMessages();
  }
  Télécharger

  Use methods that return a boolean for instance when registering menu items or widgets.

  public function configureAdminMenu(MenuAdmin $menu)
  {
      if (Piwik::hasUserSuperUserAccess()) {
          $menu->addPlatformItem('Plugins', $this->urlForDefaultAction());
      }
  }
  Télécharger

  It is important to be aware that just because the menu item won’t be displayed in the UI a user can still open the registered URL manually. Therefore you have to check for permissions in the actual controller action as well.

  View permission

  A user having a view permission should be only able to view reports but not make any changes apart from his personal settings. The methods that end with UserHasSomeViewAccess make sure a user has at least view permission for one website whereas the methods *UserHasViewAccess($idSites = array(1,2,3)) check whether a user has view access for all of the given websites.

  Piwik::checkUserHasSomeViewAccess();
   
  Piwik::checkUserHasViewAccess($idSites = array(1,2,3));
  Télécharger

  As a plugin developer you would usually use the latter example to verify the permissions for specific websites. Use the first example in case you develop something like an “All Websites Dashboard” where you only want to make sure the user has a view permission for at least one website.

  Admin permission

  A user having an admin permission cannot only view reports but also change website related settings. The methods to check for this role are similar to the ones before, just swap the term View with Admin.

  Piwik::checkUserHasSomeAdminAccess();
   
  Piwik::checkUserHasAdminAccess($idSites = array(1,2,3));
  Télécharger

  Super user permission

  A user having the super user permission is allowed to access all of the data stored in Piwik and change any settings. To check if a user has this role use one of the methods that end with UserSuperUserAccess.

  Piwik::checkUserHasSuperUserAccess();

  As a plugin developer you would check for this permission for instance in places where your plugin shows an activity log over all users or where it offers the possibility to change any system wide settings.

  Getting information about the currently logged in user

  Sometimes you might want to know which user is currently logged in. This can be useful if you want to persist user related information in the database or if you want to send an email to the currently logged in user. You can easily get this information by calling the following methods :

  $login = Piwik::getCurrentUserLogin()
  $email = Piwik::getCurrentUserEmail()
  Télécharger

  Advanced features

  Of course there is more that you can do. For instance you can verify whether a user is an anonymous user or whether a user has a specific role. You can also perform any operation in the context of a super user even if the current user does not have this role. Would you like to know more about those features ? Check out the Piwik class reference, the Security guide and the Manage Users user guide.

  If you have any feedback regarding our APIs or our guides in the Developer Zone feel free to send it to us.