autometal-piwik 0.2.3

data/History.txt

@@ -0,0 +1,9 @@
+== 0.0.2 2008-07-22
+
+* Added specs for existing API methods
+* Created RubyForge project at http://rubyforge.org/projects/piwik/
+
+== 0.0.1 2008-07-21
+
+* 1 major enhancement:
+  * Initial release

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Riopro Informática Ltda
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,20 @@
+History.txt
+License.txt
+Manifest.txt
+PostInstall.txt
+README.rdoc
+Rakefile
+Todo.txt
+autometal-piwik.gemspec
+lib/piwik.rb
+lib/piwik/base.rb
+lib/piwik/site.rb
+lib/piwik/user.rb
+script/console
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+test/files/config/piwik.yml
+test/piwik_test.rb
+test/test_helper.rb

data/PostInstall.txt

@@ -0,0 +1,4 @@
+
+For more information on piwik, see http://piwik.rubyforge.org or 
+http://github.com/Achillefs/piwik/
+

data/README.rdoc

@@ -0,0 +1,81 @@
+= autometal-piwik
+
+* http://github.com/riopro/Achillefs/tree/master
+* http://humbuckercode.co.uk/licks/gems/piwik
+
+== DESCRIPTION:
+
+A simple Ruby client for the Piwik API. This gem is based on Rodrigo Tassinari de Oliveira's piwik gem (https://github.com/riopro/piwik). Since it hasn't been updated since 2008, I took the liberty to fork it, and finish it up.
+
+== FEATURES/PROBLEMS:
+
+* Object-oriented interface to the Piwik API;
+* For now, only a small subset of the API is implemented (only basic actions)
+
+== SYNOPSIS:
+
+Piwik is an open source web analytics software, written in PHP. It provides an 
+extensive REST-like API, and this gem aims to be a simple Ruby wrapper to access 
+this API in a Ruby-friendly way. For example:
+
+  require 'rubygems'
+  require 'piwik'
+  site = Piwik::Site.load(1, 'http://your.piwi.install', 'some_auth_key')
+  => #<Piwik::Site:0xb74bf994 @name="Example.com", @config={:auth_token=>"some_auth_key", :piwik_url=>"http://your.piwi.install"}, @id=1, @main_url="http://www.example.com", @created_at=Tue Jul 15 18:55:40 -0300 2008>
+  site.pageviews(:month, Date.today)
+  => 88
+
+Currently, only Piwik::Site simple new / create / save / update methods have been implemented.
+
+For more information on Piwik and it's API, see the Piwik website (http://piwik.org) 
+and the Piwik API reference (http://dev.piwik.org/trac/wiki/API/Reference).
+
+== REQUIREMENTS:
+
+RubyGems and the following gems (installed automatically if necessary):
+
+  active_support
+  xml-simple
+  rest-client
+
+== INSTALL:
+
+  sudo gem install autometal-piwik --source=http://gemcutter.org
+
+== CHANGELOG:
+ * 0.2.3
+   Started adding some tests
+ * 0.2.0
+   Reworked plugin to also look for a rails config file called piwik.yml, and not just the .piwik user prefs file.
+ * 0.0.2 2008-07-22 (riopro)
+   * Added specs for existing API methods
+   * Created RubyForge project at http://rubyforge.org/projects/piwik/
+ * 0.0.1 2008-07-21 (riopro)
+   * major enhancement:
+   * Initial release
+
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2011 Achillefs Charmpilas, Humbucker Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,16 @@
+require 'rubygems'
+gem 'hoe', '>= 2.1.0'
+require 'hoe'
+require 'fileutils'
+require './lib/piwik'
+
+Hoe.plugin :newgem
+$hoe = Hoe.spec 'autometal-piwik' do
+  self.developer 'Achillefs Charmpilas', 'ac@humbuckercode.co.uk'
+  self.post_install_message = File.read('PostInstall.txt')
+  self.rubyforge_name       = self.name
+  self.extra_deps         = [['activesupport','>= 2.3.8'],['xml-simple',">=1.0.11"],["rest-client",">= 0.5.1"]]
+end
+
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }

data/Todo.txt

@@ -0,0 +1,6 @@
+TODO:
+=====
+
+* Implement the rest of the API for a site
+* Model the User object, and implement it's API methods
+* Add tests

data/autometal-piwik.gemspec

@@ -0,0 +1,50 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{autometal-piwik}
+  s.version = "0.2.3"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Achillefs Charmpilas"]
+  s.date = %q{2011-01-17}
+  s.description = %q{A simple Ruby client for the Piwik API. This gem is based on Rodrigo Tassinari de Oliveira's piwik gem (https://github.com/riopro/piwik). Since it hasn't been updated since 2008, I took the liberty to fork it, and finish it up.}
+  s.email = ["ac@humbuckercode.co.uk"]
+  s.extra_rdoc_files = ["History.txt", "License.txt", "Manifest.txt", "PostInstall.txt", "Todo.txt"]
+  s.files = ["History.txt", "License.txt", "Manifest.txt", "PostInstall.txt", "README.rdoc", "Rakefile", "Todo.txt", "autometal-piwik.gemspec", "lib/piwik.rb", "lib/piwik/base.rb", "lib/piwik/site.rb", "lib/piwik/user.rb", "script/console", "script/destroy", "script/generate", "script/txt2html", "setup.rb", "spec/piwik_spec.rb", "spec/spec.opts", "spec/spec_helper.rb", "test/test_helper.rb"]
+  s.homepage = %q{http://github.com/riopro/Achillefs/tree/master}
+  s.post_install_message = %q{
+For more information on piwik, see http://piwik.rubyforge.org or 
+http://github.com/Achillefs/piwik/
+
+}
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{autometal-piwik}
+  s.rubygems_version = %q{1.4.2}
+  s.summary = %q{A simple Ruby client for the Piwik API}
+  s.test_files = ["test/test_helper.rb"]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<activesupport>, [">= 2.3.8"])
+      s.add_runtime_dependency(%q<xml-simple>, [">= 1.0.11"])
+      s.add_runtime_dependency(%q<rest-client>, [">= 0.5.1"])
+      s.add_development_dependency(%q<rubyforge>, [">= 2.0.4"])
+      s.add_development_dependency(%q<hoe>, [">= 2.6.2"])
+    else
+      s.add_dependency(%q<activesupport>, [">= 2.3.8"])
+      s.add_dependency(%q<xml-simple>, [">= 1.0.11"])
+      s.add_dependency(%q<rest-client>, [">= 0.5.1"])
+      s.add_dependency(%q<rubyforge>, [">= 2.0.4"])
+      s.add_dependency(%q<hoe>, [">= 2.6.2"])
+    end
+  else
+    s.add_dependency(%q<activesupport>, [">= 2.3.8"])
+    s.add_dependency(%q<xml-simple>, [">= 1.0.11"])
+    s.add_dependency(%q<rest-client>, [">= 0.5.1"])
+    s.add_dependency(%q<rubyforge>, [">= 2.0.4"])
+    s.add_dependency(%q<hoe>, [">= 2.6.2"])
+  end
+end

data/lib/piwik.rb

@@ -0,0 +1,10 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'piwik/base.rb'
+require 'piwik/site.rb'
+require 'piwik/user.rb'
+
+module Piwik
+  VERSION = "0.2.3"
+end

data/lib/piwik/base.rb

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'cgi'
+require 'active_support'
+require 'rest_client'
+require 'xmlsimple'
+
+module Piwik
+  class ApiError < StandardError; end
+  class MissingConfiguration < ArgumentError; end
+  class UnknownSite < ArgumentError; end
+  class UnknownUser < ArgumentError; end
+
+  class Base
+    @@template  = <<-EOF
+# .piwik
+# 
+# Please fill in fields like this:
+#
+#  piwik_url: http://your.piwik.site
+#  auth_token: secret
+#
+piwik_url: 
+auth_token: 
+EOF
+      
+    private
+      # Checks for the config, creates it if not found
+      def self.load_config_from_file
+        config = {}
+        if defined?(RAILS_ROOT) and RAILS_ROOT != nil
+          home =  RAILS_ROOT
+          filename = "config/piwik.yml"
+        else
+          home =  ENV['HOME'] || ENV['USERPROFILE'] || ENV['HOMEPATH'] || "."
+          filename = ".piwik"
+        end
+        temp_config = if File.exists?(File.join(home,filename))
+          YAML::load(open(File.join(home,filename)))
+        else
+          open(File.join(home,filename),'w') { |f| f.puts @@template }
+          YAML::load(@@template)
+        end
+        temp_config.each { |k,v| config[k.to_sym] = v } if temp_config
+        if config[:piwik_url] == nil || config[:auth_token] == nil
+          if defined?(RAILS_ROOT) and RAILS_ROOT != nil
+            raise MissingConfiguration, "Please edit ./config/piwik.yml to include your piwik url and auth_key"
+          else
+            raise MissingConfiguration, "Please edit ~/.piwik to include your piwik url and auth_key"
+          end
+          
+        end
+        config
+      end
+  end
+end

data/lib/piwik/site.rb

@@ -0,0 +1,252 @@
+module Piwik
+  class Site < Piwik::Base
+    attr_accessor :name, :main_url
+    attr_reader :id, :created_at, :config
+    
+    # Initializes a new <tt>Piwik::Site</tt> object, with the supplied attributes. 
+    # 
+    # You can pass the URL for your Piwik install and an authorization token as 
+    # the second and third parameters. If you don't, than it will try to find 
+    # them in a <tt>'~/.piwik'</tt> (and create the file with an empty template if it 
+    # doesn't exists).
+    # 
+    # Valid (and required) attributes are:
+    # * <tt>:name</tt> - the site's name
+    # * <tt>:main_url</tt> - the site's url
+    def initialize(attributes={}, piwik_url=nil, auth_token=nil)
+      raise ArgumentError, "expected an attributes Hash, got #{attributes.inspect}" unless attributes.is_a?(Hash)
+      @config = if piwik_url.nil? || auth_token.nil?
+        self.class.load_config_from_file
+      else
+        {:piwik_url => piwik_url, :auth_token => auth_token}
+      end
+      load_attributes(attributes)
+    end
+  
+    # Returns an instance of <tt>Piwik::Site</tt> representing the site identified by 
+    # the supplied <tt>site_id</tt>. Raises a <tt>Piwik::ApiError</tt> if the site doesn't 
+    # exists or if the user associated with the supplied auth_token does not 
+    # have at least 'view' access to the site.
+    # 
+    # You can pass the URL for your Piwik install and an authorization token as 
+    # the second and third parameters. If you don't, than it will try to find 
+    # them in a <tt>'~/.piwik'</tt> (and create the file with an empty template if it 
+    # doesn't exists).
+    def self.load(site_id, piwik_url=nil, auth_token=nil)
+      raise ArgumentError, "expected a site Id" if site_id.nil?
+      @config = if piwik_url.nil? || auth_token.nil?
+        load_config_from_file
+      else
+        {:piwik_url => piwik_url, :auth_token => auth_token}
+      end
+      attributes = get_site_attributes_by_id(site_id, @config[:piwik_url], @config[:auth_token])
+      new(attributes, @config[:piwik_url], @config[:auth_token])
+    end
+    
+    # Returns <tt>true</tt> if the current site does not exists in the Piwik yet.
+    def new?
+      id.nil? && created_at.nil?
+    end
+    
+    # Saves the current site in Piwik.
+    # 
+    # Calls <tt>create</tt> it it's a new site, <tt>update</tt> otherwise.
+    def save
+      new? ? create : update
+    end
+    
+    # Saves the current new site in Piwik.
+    # 
+    # Equivalent Piwik API call: SitesManager.addSite (siteName, urls)
+    def create
+      raise ArgumentError, "Site already exists in Piwik, call 'update' instead" unless new?
+      raise ArgumentError, "Name can not be blank" if name.blank?
+      raise ArgumentError, "Main URL can not be blank" if main_url.blank?
+      xml = call('SitesManager.addSite', :siteName => name, :urls => main_url)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      @id = result["result"].to_i
+      @created_at = Time.current
+      id && id > 0 ? true : false
+    end
+    
+    # Saves the current site in Piwik, updating it's data.
+    # 
+    # Equivalent Piwik API call: SitesManager.updateSite (idSite, siteName, urls)
+    def update
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      raise ArgumentError, "Name can not be blank" if name.blank?
+      raise ArgumentError, "Main URL can not be blank" if main_url.blank?
+      xml = call('SitesManager.updateSite', :idSite => id, :siteName => name, :urls => main_url)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      result['success'] ? true : false
+    end
+    
+    def reload
+      #TODO
+    end
+    
+    # Deletes the current site from Piwik.
+    # 
+    # Equivalent Piwik API call: SitesManager.deleteSite (idSite)
+    def destroy
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      xml = call('SitesManager.deleteSite', :idSite => id)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      freeze
+      result['success'] ? true : false
+    end
+    
+    # Gives read access (<tt>'view'</tt>) to the supplied user login for the current
+    # site.
+    def give_view_access_to(login)
+      give_access_to(:view, login)
+    end
+    
+    # Gives read and write access (<tt>'admin'</tt>) for the supplied user login for the 
+    # current site.
+    def give_admin_access_to(login)
+      give_access_to(:admin, login)
+    end
+    
+    # Removes all access (gives an <tt>'noaccess'</tt>) for the supplied user login for 
+    # the current site.
+    def give_no_access_to(login)
+      give_access_to(:noaccess, login)
+    end
+    alias_method :remove_access_from, :give_no_access_to
+    
+    # Returns a hash with a summary of access information for the current site 
+    # (visits, unique visitors, actions / pageviews, maximum actions per visit, 
+    # bounces and total time spent in all visits in seconds), filtered by the 
+    # supplied period and date.
+    # 
+    # * <tt>period</tt> should be one of <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt> or <tt>:year</tt> (default: <tt>:day</tt>)
+    # * <tt>date</tt> should be a <tt>Date</tt> object (default: <tt>Date.today</tt>)
+    # 
+    # Equivalent Piwik API call: VisitsSummary.get (idSite, period, date)
+    def summary(period=:day, date=Date.today)
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      xml = call('VisitsSummary.get', :idSite => id, :period => period, :date => date)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      {
+        :visits => result['nb_visits'].to_i,
+        :unique_visitors => result['nb_uniq_visitors'].to_i,
+        :actions => result['nb_actions'].to_i,
+        :max_actions_per_visit => result['max_actions'].to_i,
+        :bounces => result['bounce_count'].to_i,
+        :total_time_spent => result['sum_visit_length'].to_i, # in seconds
+      }
+    end
+    
+    # Returns the amount of visits for the current site, filtered by the 
+    # supplied period and date.
+    # 
+    # * <tt>period</tt> should be one of <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt> or <tt>:year</tt> (default: <tt>:day</tt>)
+    # * <tt>date</tt> should be a <tt>Date</tt> object (default: <tt>Date.today</tt>)
+    # 
+    # Equivalent Piwik API call: VisitsSummary.getVisits (idSite, period, date)
+    def visits(period=:day, date=Date.today)
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      xml = call('VisitsSummary.getVisits', :idSite => id, :period => period, :date => date)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      result.to_i
+    end
+    
+    # Returns the amount of unique visitors for the current site, filtered by 
+    # the supplied period and date.
+    # 
+    # * <tt>period</tt> should be one of <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt> or <tt>:year</tt> (default: <tt>:day</tt>)
+    # * <tt>date</tt> should be a <tt>Date</tt> object (default: <tt>Date.today</tt>)
+    # 
+    # Equivalent Piwik API call: VisitsSummary.getUniqueVisitors (idSite, period, date)
+    def unique_visitors(period=:day, date=Date.today)
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      xml = call('VisitsSummary.getUniqueVisitors', :idSite => id, :period => period, :date => date)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      result.to_i
+    end
+    
+    # Returns the amount of actions (pageviews) for the current site, filtered 
+    # by the supplied period and date.
+    # 
+    # * <tt>period</tt> should be one of <tt>:day</tt>, <tt>:week</tt>, <tt>:month</tt> or <tt>:year</tt> (default: <tt>:day</tt>)
+    # * <tt>date</tt> should be a <tt>Date</tt> object (default: <tt>Date.today</tt>)
+    # 
+    # Equivalent Piwik API call: VisitsSummary.getActions (idSite, period, date)
+    def actions(period=:day, date=Date.today)
+      raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+      xml = call('VisitsSummary.getActions', :idSite => id, :period => period, :date => date)
+      result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+      result.to_i
+    end
+    alias_method :pageviews, :actions
+    
+    private
+      # Calls the supplied Piwik API method, with the supplied parameters.
+      # 
+      # Returns a string containing the XML reply from Piwik, or raises a 
+      # <tt>Piwik::ApiError</tt> exception with the error message returned by Piwik 
+      # in case it receives an error.
+      def call(method, params={})
+        self.class.call(method, params, config[:piwik_url], config[:auth_token])
+      end
+    
+      # Loads the attributes in the instance variables.
+      def load_attributes(attributes)
+        @id = attributes[:id]
+        @name = attributes[:name]
+        @main_url = attributes[:main_url] ? attributes[:main_url].gsub(/\/$/, '') : nil
+        @created_at = attributes[:created_at]
+      end
+
+      # Gives the supplied access for the supplied user, for the current site.
+      # 
+      # * <tt>access</tt> can be one of <tt>:view</tt>, <tt>:admin</tt> or <tt>:noaccess</tt>
+      # * <tt>login</tt> is the user login on Piwik
+      # 
+      # Equivalent Piwik API call: UsersManager.setUserAccess (userLogin, access, idSites)
+      def give_access_to(access, login)
+        raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
+        xml = call('UsersManager.setUserAccess', :idSites => id, :access => access.to_s, :userLogin => login.to_s)
+        result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+        result['success'] ? true : false
+      end
+
+      # Calls the supplied Piwik API method, with the supplied parameters.
+      # 
+      # Returns a string containing the XML reply from Piwik, or raises a 
+      # <tt>Piwik::ApiError</tt> exception with the error message returned by Piwik 
+      # in case it receives an error.
+      def self.call(method, params={}, piwik_url=nil, auth_token=nil)
+        raise MissingConfiguration, "Please edit ~/.piwik to include your piwik url and auth_key" if piwik_url.nil? || auth_token.nil?
+        url = "#{piwik_url}/?module=API&format=xml&method=#{method}"
+        url << "&token_auth=#{auth_token}" unless auth_token.nil?
+        params.each { |k, v| url << "&#{k}=#{CGI.escape(v.to_s)}" }
+        verbose_obj_save = $VERBOSE
+        $VERBOSE = nil # Suppress "warning: peer certificate won't be verified in this SSL session"
+        xml = RestClient.get(url)
+        $VERBOSE = verbose_obj_save
+        if xml =~ /error message=/
+          result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+          raise ApiError, result['error']['message'] if result['error']
+        end
+        xml
+      end
+
+      # Returns a hash with the attributes of the supplied site, identified 
+      # by it's Id in <tt>site_id</tt>.
+      # 
+      # Equivalent Piwik API call: SitesManager.getSiteFromId (idSite)
+      def self.get_site_attributes_by_id(site_id, piwik_url, auth_token)
+        xml = call('SitesManager.getSiteFromId', {:idSite => site_id}, piwik_url, auth_token)
+        result = XmlSimple.xml_in(xml, {'ForceArray' => false})
+        attributes = {
+          :id => result['row']['idsite'].to_i,
+          :name => result['row']['name'],
+          :main_url => result['row']['main_url'],
+          :created_at => Time.parse(result['row']['ts_created']),
+        }
+        attributes
+      end
+  end
+end