Changeset 25077


Ignore:
Timestamp:
Oct 22, 2013, 2:58:58 PM (7 years ago)
Author:
mistic100
Message:

feature:2982 API: add high-level type check
introduces some constants fro bool, int, float, positive and notnull parameters
types are tested in PwgServer::invoke and no in each method
+ some optimizations + update methods descriptions

Location:
trunk
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/include/ws_core.inc.php

    r25025 r25077  
    3636define( 'WS_PARAM_OPTIONAL',      0x040000 );
    3737
     38define( 'WS_TYPE_BOOL',           0x01 );
     39define( 'WS_TYPE_INT',            0x02 );
     40define( 'WS_TYPE_FLOAT',          0x04 );
     41define( 'WS_TYPE_POSITIVE',       0x10 );
     42define( 'WS_TYPE_NOTNULL',        0x20 );
     43define( 'WS_TYPE_ID', WS_TYPE_INT | WS_TYPE_POSITIVE | WS_TYPE_NOTNULL);
     44
    3845define( 'WS_ERR_INVALID_METHOD',  501 );
    3946define( 'WS_ERR_MISSING_PARAM',   1002 );
     
    274281    }
    275282
    276     $this->addMethod('reflection.getMethodList',
    277         array('PwgServer', 'ws_getMethodList'),
    278         null, '' );
    279     $this->addMethod('reflection.getMethodDetails',
     283    // add reflection methods
     284    $this->addMethod(
     285        'reflection.getMethodList',
     286        array('PwgServer', 'ws_getMethodList')
     287        );
     288    $this->addMethod(
     289        'reflection.getMethodDetails',
    280290        array('PwgServer', 'ws_getMethodDetails'),
    281         array('methodName'),'');
     291        array('methodName')
     292        );
    282293
    283294    trigger_action('ws_add_methods', array(&$this) );
     
    303314   * @param methodName string - the name of the method as seen externally
    304315   * @param callback mixed - php method to be invoked internally
    305    * @param params array - map of allowed parameter names with optional default
    306    *   values and parameter flags. Example of $params:
    307    *     array( 'param1' => array('default'=>523, 'flags'=>WS_PARAM_FORCE_ARRAY) ).
    308    *   Possible parameter flags are:
    309    *     WS_PARAM_ALLOW_ARRAY - this parameter can be an array
    310    *     WS_PARAM_FORCE_ARRAY - if this parameter is scalar, force it to an array
    311    *       before invoking the method
     316   * @param params array - map of allowed parameter names with options
     317   *    @option mixed default (optional)
     318   *    @option int flags (optional)
     319   *      possible values: WS_PARAM_ALLOW_ARRAY, WS_PARAM_FORCE_ARRAY, WS_PARAM_OPTIONAL
     320   *    @option int type (optional)
     321   *      possible values: WS_TYPE_BOOL, WS_TYPE_INT, WS_TYPE_FLOAT, WS_TYPE_ID
     322   *                       WS_TYPE_POSITIVE, WS_TYPE_NOTNULL
     323   *    @option int|float maxValue (optional)
    312324   * @param description string - a description of the method.
    313325   * @param include_file string - a file to be included befaore the callback is executed
    314    * @param options array - Available options are:
    315    *   hidden - if true, this method won't be visible by reflection.getMethodList
    316    */
    317   function addMethod($methodName, $callback, $params=array(), $description, $include_file='', $options=array())
     326   * @param options array
     327   *    @option bool hidden (hidden) - if true, this method won't be visible by reflection.getMethodList
     328   */
     329  function addMethod($methodName, $callback, $params=array(), $description='', $include_file='', $options=array())
    318330  {
    319331    if (!is_array($params))
     
    331343      if ( !is_array($data) )
    332344      {
    333         $params[$param] = array('flags'=>0);
     345        $params[$param] = array('flags'=>0,'type'=>0);
    334346      }
    335347      else
    336348      {
    337         $flags = isset($data['flags']) ? $data['flags'] : 0;
     349        if ( !isset($data['flags']) )
     350        {
     351          $data['flags'] = 0;
     352        }
    338353        if ( array_key_exists('default', $data) )
    339354        {
    340           $flags |= WS_PARAM_OPTIONAL;
    341         }
    342         $data['flags'] = $flags;
     355          $data['flags'] |= WS_PARAM_OPTIONAL;
     356        }
     357        if ( !isset($data['type']) )
     358        {
     359          $data['type'] = 0;
     360        }
    343361        $params[$param] = $data;
    344362      }
     
    376394  }
    377395
    378   /*static*/ function makeArrayParam(&$param)
     396  static function makeArrayParam(&$param)
    379397  {
    380398    if ( $param==null )
     
    384402    else
    385403    {
    386       if (! is_array($param) )
     404      if ( !is_array($param) )
    387405      {
    388406        $param = array($param);
    389407      }
    390408    }
     409  }
     410 
     411  static function checkType(&$param, $type, $name)
     412  {
     413    $opts = array();
     414    $msg = '';
     415    if ( self::hasFlag($type, WS_TYPE_POSITIVE | WS_TYPE_NOTNULL) )
     416    {
     417      $opts['options']['min_range'] = 1;
     418      $msg = ' positive and not null';
     419    }
     420    else if ( self::hasFlag($type, WS_TYPE_POSITIVE) )
     421    {
     422      $opts['options']['min_range'] = 0;
     423      $msg = ' positive';
     424    }
     425   
     426    if ( is_array($param) )
     427    {
     428      if ( self::hasFlag($type, WS_TYPE_BOOL) )
     429      {
     430        foreach ($param as &$value)
     431        {
     432          if ( ($value = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE)) === null )
     433          {
     434            return new PwgError(WS_ERR_INVALID_PARAM, $name.' must only contain booleans' );
     435          }
     436        }
     437        unset($value);
     438      }
     439      else if ( self::hasFlag($type, WS_TYPE_INT) )
     440      {
     441        foreach ($param as &$value)
     442        {
     443          if ( ($value = filter_var($value, FILTER_VALIDATE_INT, $opts)) === false )
     444          {
     445            return new PwgError(WS_ERR_INVALID_PARAM, $name.' must only contain'.$msg.' integers' );
     446          }
     447        }
     448        unset($value);
     449      }
     450      else if ( self::hasFlag($type, WS_TYPE_FLOAT) )
     451      {
     452        foreach ($param as &$value)
     453        {
     454          if (
     455            ($value = filter_var($value, FILTER_VALIDATE_FLOAT)) === false
     456            or ( isset($opts['options']['min_range']) and $value < $opts['options']['min_range'] )
     457          ) {
     458            return new PwgError(WS_ERR_INVALID_PARAM, $name.' must only contain'.$msg.' floats' );
     459          }
     460        }
     461        unset($value);
     462      }
     463    }
     464    else if ( $param !== '' )
     465    {
     466      if ( self::hasFlag($type, WS_TYPE_BOOL) )
     467      {
     468        if ( ($param = filter_var($param, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE)) === null )
     469        {
     470          return new PwgError(WS_ERR_INVALID_PARAM, $name.' must be a boolean' );
     471        }
     472      }
     473      else if ( self::hasFlag($type, WS_TYPE_INT) )
     474      {
     475        if ( ($param = filter_var($param, FILTER_VALIDATE_INT, $opts)) === false )
     476        {
     477          return new PwgError(WS_ERR_INVALID_PARAM, $name.' must be an'.$msg.' integer' );
     478        }
     479      }
     480      else if ( self::hasFlag($type, WS_TYPE_FLOAT) )
     481      {
     482        if (
     483          ($param = filter_var($param, FILTER_VALIDATE_FLOAT)) === false
     484          or ( isset($opts['options']['min_range']) and $param < $opts['options']['min_range'] )
     485        ) {
     486          return new PwgError(WS_ERR_INVALID_PARAM, $name.' must be a'.$msg.' float' );
     487        }
     488      }
     489    }
     490   
     491    return null;
     492  }
     493 
     494  static function hasFlag($val, $flag)
     495  {
     496    return ($val & $flag) == $flag;
    391497  }
    392498
     
    401507    $method = @$this->_methods[$methodName];
    402508
    403     if ( $method==null )
     509    if ( $method == null )
    404510    {
    405511      return new PwgError(WS_ERR_INVALID_METHOD, 'Method name is not valid');
    406512    }
    407513
    408     // parameter check and data coercion !
     514    // parameter check and data correction
    409515    $signature = $method['signature'];
    410516    $missing_params = array();
    411     foreach($signature as $name=>$options)
     517   
     518    foreach ($signature as $name => $options)
    412519    {
    413520      $flags = $options['flags'];
     521     
     522      // parameter not provided in the request
    414523      if ( !array_key_exists($name, $params) )
    415       {// parameter not provided in the request
    416         if ( !($flags&WS_PARAM_OPTIONAL) )
     524      {
     525        if ( !self::hasFlag($flags, WS_PARAM_OPTIONAL) )
    417526        {
    418527          $missing_params[] = $name;
    419528        }
    420         else if ( array_key_exists('default',$options) )
     529        else if ( array_key_exists('default', $options) )
    421530        {
    422531          $params[$name] = $options['default'];
    423           if ( ($flags&WS_PARAM_FORCE_ARRAY)==WS_PARAM_FORCE_ARRAY )
     532          if ( self::hasFlag($flags, WS_PARAM_FORCE_ARRAY) )
    424533          {
    425             $this->makeArrayParam( $params[$name] );
     534            self::makeArrayParam($params[$name]);
    426535          }
    427536        }
    428537      }
     538      // parameter provided but empty
     539      else if ( $params[$name]==='' and !self::hasFlag($flags, WS_PARAM_OPTIONAL) )
     540      {
     541        $missing_params[] = $name;
     542      }
     543      // parameter provided - do some basic checks
    429544      else
    430       {// parameter provided - do some basic checks
     545      {
    431546        $the_param = $params[$name];
    432         if ( is_array($the_param) and ($flags&WS_PARAM_ACCEPT_ARRAY)==0 )
     547       
     548        if ( is_array($the_param) and !self::hasFlag($flags, WS_PARAM_ACCEPT_ARRAY) )
    433549        {
    434550          return new PwgError(WS_ERR_INVALID_PARAM, $name.' must be scalar' );
    435551        }
    436         if ( ($flags&WS_PARAM_FORCE_ARRAY)==WS_PARAM_FORCE_ARRAY )
    437         {
    438           $this->makeArrayParam( $the_param );
    439         }
     552       
     553        if ( self::hasFlag($flags, WS_PARAM_FORCE_ARRAY) )
     554        {
     555          self::makeArrayParam($the_param);
     556        }
     557       
     558        if ( $options['type'] > 0 )
     559        {
     560          if ( ($ret = self::checkType($the_param, $options['type'], $name)) !== null )
     561          {
     562            return $ret;
     563          }
     564        }
     565       
    440566        if ( isset($options['maxValue']) and $the_param>$options['maxValue'])
    441567        {
    442568          $the_param = $options['maxValue'];
    443569        }
     570       
    444571        $params[$name] = $the_param;
    445572      }
    446573    }
     574   
    447575    if (count($missing_params))
    448576    {
    449577      return new PwgError(WS_ERR_MISSING_PARAM, 'Missing parameters: '.implode(',',$missing_params));
    450578    }
     579   
    451580    $result = trigger_event('ws_invoke_allowed', true, $methodName, $params);
    452581    if ( strtolower( @get_class($result) )!='pwgerror')
     
    458587      $result = call_user_func_array($method['callback'], array($params, &$this) );
    459588    }
     589   
    460590    return $result;
    461591  }
     
    477607  {
    478608    $methodName = $params['methodName'];
     609   
    479610    if (!$service->hasMethod($methodName))
    480611    {
    481       return new PwgError(WS_ERR_INVALID_PARAM,
    482             'Requested method does not exist');
    483     }
     612      return new PwgError(WS_ERR_INVALID_PARAM, 'Requested method does not exist');
     613    }
     614   
    484615    $res = array(
    485616      'name' => $methodName,
     
    487618      'params' => array(),
    488619    );
    489     $signature = $service->getMethodSignature($methodName);
    490     foreach ($signature as $name => $options)
     620   
     621    foreach ($service->getMethodSignature($methodName) as $name => $options)
    491622    {
    492623      $param_data = array(
    493624        'name' => $name,
    494         'optional' => ($options['flags']&WS_PARAM_OPTIONAL)?true:false,
    495         'acceptArray' => ($options['flags']&WS_PARAM_ACCEPT_ARRAY)?true:false,
     625        'optional' => self::hasFlag($options['flags'], WS_PARAM_OPTIONAL),
     626        'acceptArray' => self::hasFlag($options['flags'], WS_PARAM_ACCEPT_ARRAY),
     627        'type' => 'mixed',
    496628        );
     629     
    497630      if (isset($options['default']))
    498631      {
     
    503636        $param_data['info'] = $options['info'];
    504637      }
     638     
     639      if ( self::hasFlag($options['type'], WS_TYPE_BOOL) )
     640      {
     641        $param_data['type'] = 'bool';
     642      }
     643      else if ( self::hasFlag($options['type'], WS_TYPE_INT) )
     644      {
     645        $param_data['type'] = 'int';
     646      }
     647      else if ( self::hasFlag($options['type'], WS_TYPE_FLOAT) )
     648      {
     649        $param_data['type'] = 'float';
     650      }
     651      if ( self::hasFlag($options['type'], WS_TYPE_POSITIVE) )
     652      {
     653        $param_data['type'].= ' positive';
     654      }
     655      if ( self::hasFlag($options['type'], WS_TYPE_NOTNULL) )
     656      {
     657        $param_data['type'].= ' notnull';
     658      }
     659     
    505660      $res['params'][] = $param_data;
    506661    }
  • trunk/include/ws_functions.inc.php

    r25019 r25077  
    227227  }
    228228
    229   if ( ($max_urls = intval($params['max_urls'])) <= 0)
    230   {
    231     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid max_urls");
    232   }
    233 
     229  $max_urls = $params['max_urls'];
    234230  list($max_id, $image_count) = pwg_db_fetch_row( pwg_query('SELECT MAX(id)+1, COUNT(*) FROM '.IMAGES_TABLE) );
    235231
     
    309305{
    310306  global $conf;
    311   if ($conf['show_version'] or is_admin() )
     307  if ( $conf['show_version'] or is_admin() )
     308  {
    312309    return PHPWG_VERSION;
     310  }
    313311  else
     312  {
    314313    return new PwgError(403, 'Forbidden');
     314  }
    315315}
    316316
     
    387387  {
    388388    return new PwgError(401, 'Access denied');
    389   }
    390   $params['image_id'] = array_map( 'intval',$params['image_id'] );
    391   if ( empty($params['image_id']) )
    392   {
    393     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
    394389  }
    395390  global $user;
     
    428423  foreach($params['cat_id'] as $cat_id)
    429424  {
    430     $cat_id = (int)$cat_id;
    431     if ($cat_id<=0)
    432       continue;
    433425    if ($params['recursive'])
    434426    {
     
    961953    return new PwgError(405, "This method requires HTTP POST");
    962954  }
    963   $params['image_id'] = (int)$params['image_id'];
     955
    964956  $query = '
    965957SELECT DISTINCT image_id
     
    10151007{
    10161008  global $user, $conf;
    1017   $params['image_id'] = (int)$params['image_id'];
    1018   if ( $params['image_id']<=0 )
    1019   {
    1020     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
    1021   }
    10221009
    10231010  $query='
     
    10291016    ).'
    10301017LIMIT 1';
    1031 
    1032   $image_row = pwg_db_fetch_assoc(pwg_query($query));
    1033   if ($image_row==null)
     1018  $result = pwg_query($query);
     1019 
     1020  if (pwg_db_num_rows($resul) == 0)
    10341021  {
    10351022    return new PwgError(404, "image_id not found");
    10361023  }
     1024 
     1025  $image_row = pwg_db_fetch_assoc($result);
    10371026  $image_row = array_merge( $image_row, ws_std_get_urls($image_row) );
    10381027
     
    12031192function ws_images_Rate($params, $service)
    12041193{
    1205   $image_id = (int)$params['image_id'];
    12061194  $query = '
    12071195SELECT DISTINCT id FROM '.IMAGES_TABLE.'
    12081196  INNER JOIN '.IMAGE_CATEGORY_TABLE.' ON id=image_id
    1209   WHERE id='.$image_id
     1197  WHERE id='.$params['image_id']
    12101198  .get_sql_condition_FandF(
    12111199    array(
     
    12221210  $rate = (int)$params['rate'];
    12231211  include_once(PHPWG_ROOT_PATH.'include/functions_rate.inc.php');
    1224   $res = rate_picture( $image_id, $rate );
     1212  $res = rate_picture( $params['image_id'], $rate );
    12251213  if ($res==false)
    12261214  {
     
    12561244      implode(' AND ', $where_clauses)
    12571245    );
    1258 
    1259   $params['per_page'] = (int)$params['per_page'];
    1260   $params['page'] = (int)$params['page'];
    12611246
    12621247  $image_ids = array_slice(
     
    13181303    return new PwgError(405, "This method requires HTTP POST");
    13191304  }
    1320   $params['image_id'] = array_map( 'intval',$params['image_id'] );
    1321   if ( empty($params['image_id']) )
    1322   {
    1323     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
    1324   }
    13251305  global $conf;
    1326   if ( !in_array( (int)$params['level'], $conf['available_permission_levels']) )
     1306  if ( !in_array($params['level'], $conf['available_permission_levels']) )
    13271307  {
    13281308    return new PwgError(WS_ERR_INVALID_PARAM, "Invalid level");
     
    13551335  }
    13561336
    1357   // is the image_id valid?
    1358   $params['image_id'] = (int)$params['image_id'];
    1359   if ($params['image_id'] <= 0)
    1360   {
    1361     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
    1362   }
    1363 
    1364   // is the category valid?
    1365   $params['category_id'] = (int)$params['category_id'];
    1366   if ($params['category_id'] <= 0)
    1367   {
    1368     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid category_id");
    1369   }
    1370 
    1371   // is the rank valid?
    1372   $params['rank'] = (int)$params['rank'];
    1373   if ($params['rank'] <= 0)
    1374   {
    1375     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid rank");
    1376   }
    1377 
    13781337  // does the image really exist?
    13791338  $query='
    1380 SELECT
    1381     *
     1339SELECT COUNT(*)
    13821340  FROM '.IMAGES_TABLE.'
    13831341  WHERE id = '.$params['image_id'].'
    13841342;';
    13851343
    1386   $image_row = pwg_db_fetch_assoc(pwg_query($query));
    1387   if ($image_row == null)
     1344  list($count) = pwg_db_fetch_row(pwg_query($query));
     1345  if ($count == 0)
    13881346  {
    13891347    return new PwgError(404, "image_id not found");
     
    13921350  // is the image associated to this category?
    13931351  $query = '
    1394 SELECT
    1395     image_id,
    1396     category_id,
    1397     rank
     1352SELECT COUNT(*)
    13981353  FROM '.IMAGE_CATEGORY_TABLE.'
    13991354  WHERE image_id = '.$params['image_id'].'
    14001355    AND category_id = '.$params['category_id'].'
    14011356;';
    1402   $category_row = pwg_db_fetch_assoc(pwg_query($query));
    1403   if ($category_row == null)
     1357  list($count) = pwg_db_fetch_row(pwg_query($query));
     1358  if ($count == 0)
    14041359  {
    14051360    return new PwgError(404, "This image is not associated to this category");
     
    16251580  {
    16261581    return new PwgError(401, 'Access denied');
    1627   }
    1628 
    1629   $params['image_id'] = (int)$params['image_id'];
    1630   if ($params['image_id'] <= 0)
    1631   {
    1632     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
    16331582  }
    16341583
     
    16471596  WHERE id = '.$params['image_id'].'
    16481597;';
    1649   $image = pwg_db_fetch_assoc(pwg_query($query));
    1650 
    1651   if ($image == null)
     1598  $result = pwg_query($query);
     1599
     1600  if (pwg_db_num_rows($result) == 0)
    16521601  {
    16531602    return new PwgError(404, "image_id not found");
    16541603  }
     1604 
     1605  $image = pwg_db_fetch_assoc($result);
    16551606
    16561607  // since Piwigo 2.4 and derivatives, we do not take the imported "thumb"
     
    17271678  }
    17281679
    1729   $params['image_id'] = (int)$params['image_id'];
    17301680  if ($params['image_id'] > 0)
    17311681  {
    17321682    $query='
    1733 SELECT *
     1683SELECT COUNT(*)
    17341684  FROM '.IMAGES_TABLE.'
    17351685  WHERE id = '.$params['image_id'].'
    17361686;';
    17371687
    1738     $image_row = pwg_db_fetch_assoc(pwg_query($query));
    1739     if ($image_row == null)
     1688    list($count) = pwg_db_fetch_row(pwg_query($query));
     1689    if ($count == 0)
    17401690    {
    17411691      return new PwgError(404, "image_id not found");
     
    17561706
    17571707    $query = '
    1758 SELECT
    1759     COUNT(*) AS counter
     1708SELECT COUNT(*)
    17601709  FROM '.IMAGES_TABLE.'
    17611710  WHERE '.$where_clause.'
     
    18801829  if (!isset($_FILES['image']))
    18811830  {
    1882     return new PwgError(405, "The image (file) parameter is missing");
    1883   }
    1884 
    1885   $params['image_id'] = (int)$params['image_id'];
     1831    return new PwgError(405, "The image (file) is missing");
     1832  }
     1833
    18861834  if ($params['image_id'] > 0)
    18871835  {
    18881836    $query='
    1889 SELECT *
     1837SELECT COUNT(*)
    18901838  FROM '.IMAGES_TABLE.'
    18911839  WHERE id = '.$params['image_id'].'
    18921840;';
    18931841
    1894     $image_row = pwg_db_fetch_assoc(pwg_query($query));
    1895     if ($image_row == null)
     1842    list($count) = pwg_db_fetch_row(pwg_query($query));
     1843    if ($count == 0)
    18961844    {
    18971845      return new PwgError(404, "image_id not found");
    18981846    }
    1899   }
    1900 
    1901   // category
    1902   $params['category'] = (int)$params['category'];
    1903   if ($params['category'] <= 0 and $params['image_id'] <= 0)
    1904   {
    1905     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid category_id");
    19061847  }
    19071848
     
    19111852    $_FILES['image']['tmp_name'],
    19121853    $_FILES['image']['name'],
    1913     $params['category'] > 0 ? array($params['category']) : null,
     1854    $params['category'],
    19141855    8,
    19151856    $params['image_id'] > 0 ? $params['image_id'] : null
     
    19321873  }
    19331874
    1934   if (count(array_keys($update)) > 0)
     1875  if (count($update) > 0)
    19351876  {
    19361877    $update['id'] = $image_id;
     
    19391880      IMAGES_TABLE,
    19401881      $update,
    1941       array('id', $update['id'])
     1882      array('id' => $update['id'])
    19421883      );
    19431884  }
     
    19701911  $url_params = array('image_id' => $image_id);
    19711912
    1972   if ($params['category'] > 0)
     1913  if (!empty($params['category']))
    19731914  {
    19741915    $query = '
    19751916SELECT id, name, permalink
    19761917  FROM '.CATEGORIES_TABLE.'
    1977   WHERE id = '.$params['category'].'
     1918  WHERE id = '.$params['category'][0].'
    19781919;';
    19791920    $result = pwg_query($query);
     
    20101951  }
    20111952
    2012   $user_id = (int)$params['user_id'];
    2013   if ($user_id<=0)
    2014   {
    2015     return new PwgError(WS_ERR_INVALID_PARAM, 'Invalid user_id');
    2016   }
    2017 
    20181953  $query = '
    20191954DELETE FROM '.RATE_TABLE.'
    2020   WHERE user_id='.$user_id;
     1955  WHERE user_id='.$params['user_id'];
    20211956
    20221957  if (!empty($params['anonymous_id']))
     
    21452080
    21462081  // first build all the tag_ids we are interested in
    2147   $params['tag_id'] = array_map( 'intval',$params['tag_id'] );
    21482082  $tags = find_tags($params['tag_id'], $params['tag_url_name'], $params['tag_name']);
    21492083  $tags_by_id = array();
     
    21692103
    21702104  $count_set = count($image_ids);
    2171   $params['per_page'] = (int)$params['per_page'];
    2172   $params['page'] = (int)$params['page'];
    21732105  $image_ids = array_slice($image_ids, $params['per_page']*$params['page'], $params['per_page'] );
    21742106
     
    22732205  }
    22742206 
    2275   if (!empty($params['visible']) and in_array($params['visible'], array('true','false')))
    2276   {
    2277     $options['visible'] = get_boolean($params['visible']);
    2278   }
    2279  
    2280   if (!empty($params['commentable']) and in_array($params['commentable'], array('true','false')) )
    2281   {
    2282     $options['commentable'] = get_boolean($params['commentable']);
    2283   }
    2284  
    22852207  if (!empty($params['comment']))
    22862208  {
     
    23682290    }
    23692291  }
    2370 
    2371   if ('filename' == $conf['uniqueness_mode'])
     2292  else if ('filename' == $conf['uniqueness_mode'])
    23722293  {
    23732294    // search among photos the list of photos already added, based on
     
    24202341  // high_sum
    24212342
    2422   $params['image_id'] = (int)$params['image_id'];
    2423   if ($params['image_id'] <= 0)
    2424   {
    2425     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
    2426   }
    2427 
    24282343  $query = '
    24292344SELECT
     
    24902405  }
    24912406
    2492   $params['image_id'] = (int)$params['image_id'];
    2493   if ($params['image_id'] <= 0)
    2494   {
    2495     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
    2496   }
    2497 
    24982407  include_once(PHPWG_ROOT_PATH.'admin/include/functions.php');
    24992408
     
    25032412  WHERE id = '.$params['image_id'].'
    25042413;';
    2505 
    2506   $image_row = pwg_db_fetch_assoc(pwg_query($query));
    2507   if ($image_row == null)
     2414  $result = pwg_query($query);
     2415 
     2416  if (pwg_db_num_rows($result) == 0)
    25082417  {
    25092418    return new PwgError(404, "image_id not found");
    25102419  }
     2420 
     2421  $image_row = pwg_db_fetch_assoc($result);
    25112422
    25122423  // database registration
     
    25652476      IMAGES_TABLE,
    25662477      $update,
    2567       array('id', $update['id'])
     2478      array('id' => $update['id'])
    25682479      );
    25692480  }
     
    26342545  }
    26352546
    2636   if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
     2547  if (get_pwg_token() != $params['pwg_token'])
    26372548  {
    26382549    return new PwgError(403, 'Invalid security token');
    26392550  }
    26402551
    2641   $params['image_id'] = preg_split(
    2642     '/[\s,;\|]/',
    2643     $params['image_id'],
    2644     -1,
    2645     PREG_SPLIT_NO_EMPTY
    2646     );
     2552  if (!is_array($params['image_id']))
     2553  {
     2554    $params['image_id'] = preg_split(
     2555      '/[\s,;\|]/',
     2556      $params['image_id'],
     2557      -1,
     2558      PREG_SPLIT_NO_EMPTY
     2559      );
     2560  }
    26472561  $params['image_id'] = array_map('intval', $params['image_id']);
    26482562
     
    28272741  // comment
    28282742
    2829   $params['category_id'] = (int)$params['category_id'];
    2830   if ($params['category_id'] <= 0)
    2831   {
    2832     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid category_id");
    2833   }
    2834 
    28352743  // database registration
    28362744  $update = array(
     
    28582766      CATEGORIES_TABLE,
    28592767      $update,
    2860       array('id', $update['id'])
     2768      array('id' => $update['id'])
    28612769      );
    28622770  }
     
    28802788  // image_id
    28812789
    2882   $params['category_id'] = (int)$params['category_id'];
    2883   if ($params['category_id'] <= 0)
    2884   {
    2885     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid category_id");
    2886   }
    2887 
    28882790  // does the category really exist?
    28892791  $query='
    2890 SELECT
    2891     *
     2792SELECT COUNT(*)
    28922793  FROM '.CATEGORIES_TABLE.'
    28932794  WHERE id = '.$params['category_id'].'
    28942795;';
    2895   $row = pwg_db_fetch_assoc(pwg_query($query));
    2896   if ($row == null)
     2796  list($count) = pwg_db_fetch_row(pwg_query($query));
     2797  if ($count == 0)
    28972798  {
    28982799    return new PwgError(404, "category_id not found");
    2899   }
    2900 
    2901   $params['image_id'] = (int)$params['image_id'];
    2902   if ($params['image_id'] <= 0)
    2903   {
    2904     return new PwgError(WS_ERR_INVALID_PARAM, "Invalid image_id");
    29052800  }
    29062801
    29072802  // does the image really exist?
    29082803  $query='
    2909 SELECT
    2910     *
     2804SELECT COUNT(*)
    29112805  FROM '.IMAGES_TABLE.'
    29122806  WHERE id = '.$params['image_id'].'
    29132807;';
    29142808
    2915   $row = pwg_db_fetch_assoc(pwg_query($query));
    2916   if ($row == null)
     2809  list($count) = pwg_db_fetch_row(pwg_query($query));
     2810  if ($count == 0)
    29172811  {
    29182812    return new PwgError(404, "image_id not found");
     
    29482842  }
    29492843
    2950   if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
     2844  if (get_pwg_token() != $params['pwg_token'])
    29512845  {
    29522846    return new PwgError(403, 'Invalid security token');
     
    29642858  }
    29652859
    2966   $params['category_id'] = preg_split(
    2967     '/[\s,;\|]/',
    2968     $params['category_id'],
    2969     -1,
    2970     PREG_SPLIT_NO_EMPTY
    2971     );
     2860  if (!is_array($params['category_id']))
     2861  {
     2862    $params['category_id'] = preg_split(
     2863      '/[\s,;\|]/',
     2864      $params['category_id'],
     2865      -1,
     2866      PREG_SPLIT_NO_EMPTY
     2867      );
     2868  }
    29722869  $params['category_id'] = array_map('intval', $params['category_id']);
    29732870
     
    30172914  }
    30182915
    3019   if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
     2916  if (get_pwg_token() != $params['pwg_token'])
    30202917  {
    30212918    return new PwgError(403, 'Invalid security token');
    30222919  }
    30232920
    3024   $params['category_id'] = preg_split(
    3025     '/[\s,;\|]/',
    3026     $params['category_id'],
    3027     -1,
    3028     PREG_SPLIT_NO_EMPTY
    3029     );
     2921  if (!is_array($params['category_id']))
     2922  {
     2923    $params['category_id'] = preg_split(
     2924      '/[\s,;\|]/',
     2925      $params['category_id'],
     2926      -1,
     2927      PREG_SPLIT_NO_EMPTY
     2928      );
     2929  }
    30302930  $params['category_id'] = array_map('intval', $params['category_id']);
    30312931
     
    30962996  // does this parent exists? This check should be made in the
    30972997  // move_categories function, not here
    3098   //
    30992998  // 0 as parent means "move categories at gallery root"
    3100   if (!is_numeric($params['parent']))
    3101   {
    3102     return new PwgError(403, 'Invalid parent input parameter');
    3103   }
    3104 
    31052999  if (0 != $params['parent']) {
    3106     $params['parent'] = intval($params['parent']);
    31073000    $subcat_ids = get_subcat_ids(array($params['parent']));
    31083001    if (count($subcat_ids) == 0)
     
    32073100  }
    32083101
    3209   if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
     3102  if (get_pwg_token() != $params['pwg_token'])
    32103103  {
    32113104    return new PwgError(403, 'Invalid security token');
     
    32413134  }
    32423135
    3243   if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
     3136  if (get_pwg_token() != $params['pwg_token'])
    32443137  {
    32453138    return new PwgError(403, 'Invalid security token');
     
    32723165  }
    32733166
    3274   if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
     3167  if (get_pwg_token() != $params['pwg_token'])
    32753168  {
    32763169    return new PwgError(403, 'Invalid security token');
    32773170  }
    32783171
    3279   if (empty($params['type']) or !in_array($params['type'], array('plugins', 'themes', 'languages')))
     3172  if (!in_array($params['type'], array('plugins', 'themes', 'languages')))
    32803173  {
    32813174    return new PwgError(403, "invalid extension type");
    3282   }
    3283 
    3284   if (empty($params['id']) or empty($params['revision']))
    3285   {
    3286     return new PwgError(null, 'Wrong parameters');
    32873175  }
    32883176
     
    33673255  }
    33683256
    3369   if (empty($params['pwg_token']) or get_pwg_token() != $params['pwg_token'])
     3257  if (get_pwg_token() != $params['pwg_token'])
    33703258  {
    33713259    return new PwgError(403, 'Invalid security token');
  • trunk/tools/ws.htm

    r23714 r25077  
    5454    background-image:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAMAAAADCAIAAADZSiLoAAAAH0lEQVQImSXHMQEAMAwCMOrfK0jIjuVL2gLBzyHJtgd7wBdU3Vt/7AAAAABJRU5ErkJggg==);
    5555  }
    56   #the_methods ul {font-size:1.1em;margin:5px 0 10px 10px;list-style:none;}
    57   #the_methods li:before {content:"\203A\00A0";font-weight:bold;color:#EB9C39;font-size:1.1em;}
    58   #the_methods li:hover:before {content:"\00A0\203A";}
     56  #methodsList {font-size:1.1em;margin:5px 0 10px 10px;list-style:none;}
     57  #methodsList li:before {content:"\203A\00A0";font-weight:bold;color:#EB9C39;font-size:1.1em;}
     58  #methodsList li:hover:before {content:"\00A0\203A";}
    5959
    6060  #the_page {margin-left:252px;border-style:solid;border-color:#cdcdcd;border-width:1px 0 0 1px;}
     
    7171  #methodParams td.input input[type="text"] {width:97%;font-size:0.9em;background:#f7f7f7;border:1px solid #ccc;border-radius:2px;}
    7272  #methodParams td.input input[type="text"]:hover, #methodParams td.input input[type="text"]:focus {border-color:#C7E2F1;border-top-color:#96BCD7;background:#fff;}
     73  #methodParams .type {display:inline-block;width:16px;height:16px;font-size:12px;line-height:16px;background:#ddd;border-radius:8px;font-weight:bold;text-align:center;color:#222;}
     74  #methodParams .subtype {vertical-align:super;}
    7375
    7476  #testForm {display:inline-block;margin-left:15px;}
     
    8890  .methodInfo {float:right;display:inline-block;width:16px;height:16px;font-size:12px;line-height:16px;background:#555;border-radius:8px;font-family:"Times New Roman",sans-serif;font-style:italic;font-weight:bold;text-align:center;color:#fff;}
    8991  .methodInfo:hover {border:none;text-shadow:none;background:#888;cursor:pointer;color:#fff;}
     92  #tiptip_content { font-size:12px; }
    9093 
    9194  #iframeWrapper {width:100%;height:300px;padding:3px 3px 20px 3px;background:#F9F9F9;border:1px solid #cdcdcd;overflow:hidden;position:relative;}
     
    156159              <td style="width:150px;">Name</td>
    157160              <td class="mini">Extra</td>
     161              <td class="mini">Type</td>
    158162              <td style="width:300px;">Value</td>
    159163              <td class="mini">Send</td>
     
    166170          <tfoot>
    167171            <tr>
    168               <td colspan="4"><b>*</b>: required parameter, <b>?</b>: optional parameter, <b>[]</b>: parameter can be an array (use a pipe | to split values)</td>
     172              <td colspan="5">
     173                <b>*</b>: required, <b>?</b>: optional, <b>[]</b>: can be an array (use a pipe | to split values)<br>
     174                <b>B</b>: boolean, <b>I</b>: integer, <b>F</b>: float, <b>+</b>: positive, <b>&oslash;</b>: not null
     175              </td>
    169176            </tr>
    170177          </tfoot>
     
    306313// display ws_url form
    307314function askForUrl() {
     315  displayError("can't contact web-services, please give absolute url to 'ws.php'");
    308316  if ($("#urlForm input[name='ws_url']").val() == "") {
    309317    $("#urlForm input[name='ws_url']").val(ws_url);
    310318  }
    311319  $("#urlForm").show();
    312   displayError("can't contact web-services, please give absolute url to 'ws.php'");
    313320}
    314321
     
    405412  if (method.params && method.params.length>0) {
    406413    for (var i=0; i<method.params.length; i++) {
    407       var isOptional = method.params[i].optional;
    408       var acceptArray = method.params[i].acceptArray;
    409       var defaultValue = method.params[i].defaultValue == null ? '' : method.params[i].defaultValue;
    410       var info = method.params[i].info == null ? '' : '<a class="methodInfo" title="'+ method.params[i].info + '">i</a>';
     414      var param = method.params[i],
     415          isOptional = param.optional,
     416          acceptArray = param.acceptArray,
     417          defaultValue = param.defaultValue == null ? '' : param.defaultValue,
     418          info = param.info == null ? '' : '<a class="methodInfo" title="'+ param.info.replace(/"/g, '&quot;') + '">i</a>',
     419          type = '';
     420     
     421      if (param.type.match(/bool/)) type+= '<span class=type>B</span>';
     422      if (param.type.match(/int/)) type+= '<span class=type>I</span>';
     423      if (param.type.match(/float/)) type+= '<span class=type>F</span>';
     424      if (param.type.match(/positive/)) type+= '<span class=subtype>+</span>';
     425      if (param.type.match(/notnull/)) type+= '<span class=subtype>&oslash;</span>';
    411426     
    412427      // if an array is direclty printed, the delimiter is a comma where we use a pipe
     
    416431
    417432      methodParams+= '<tr>'+
    418         '<td>'+ method.params[i].name + info +'</td>'+
     433        '<td>'+ param.name + info +'</td>'+
    419434        '<td class="mini">'+ (isOptional ? '?':'*') + (acceptArray ? ' []':'') +'</td>'+
     435        '<td class="mini">'+ type +'</td>'+
    420436        '<td class="input"><input type="text" class="methodParameterValue" data-id="'+ i +'" value="'+ defaultValue +'"></td>'+
    421437        '<td class="mini"><input type="checkbox" class="methodParameterSend" data-id="'+ i +'" '+ (isOptional ? '':'checked="checked"') +'></td>'+
     
    439455  // tiptip
    440456  $(".methodInfo").tipTip({
    441     activation:"click",
    442457    maxWidth:"300px",
    443458    defaultPosition:"right",
    444     keepAlive:true,
    445459    delay:0
    446460  });
  • trunk/ws.php

    r20817 r25077  
    104104  include_once(PHPWG_ROOT_PATH.'include/ws_functions.inc.php');
    105105 
     106  $f_params = array(
     107    'f_min_rate' => array('default'=>null,
     108                          'type'=>WS_TYPE_FLOAT),
     109    'f_max_rate' => array('default'=>null,
     110                          'type'=>WS_TYPE_FLOAT),
     111    'f_min_hit' =>  array('default'=>null,
     112                          'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     113    'f_max_hit' =>  array('default'=>null,
     114                          'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     115    'f_min_ratio' => array('default'=>null,
     116                           'type'=>WS_TYPE_FLOAT|WS_TYPE_POSITIVE),
     117    'f_max_ratio' => array('default'=>null,
     118                           'type'=>WS_TYPE_FLOAT|WS_TYPE_POSITIVE),
     119    'f_max_level' => array('default'=>null,
     120                           'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     121    'f_min_date_available' => array('default'=>null),
     122    'f_max_date_available' => array('default'=>null),
     123    'f_min_date_created' =>   array('default'=>null),
     124    'f_max_date_created' =>   array('default'=>null),
     125    );
     126 
    106127  $service->addMethod(
    107128      'pwg.getVersion',
    108129      'ws_getVersion',
    109130      null,
    110       'retrieves the PWG version'
     131      'Returns the Piwigo version.'
    111132    );
    112133         
     
    115136      'ws_getInfos',
    116137      null,
    117       'retrieves general informations'
     138      '<b>Admin only.</b> Returns general informations.'
    118139    );
    119140
     
    122143      'ws_caddie_add',
    123144      array(
    124         'image_id'=> array('flags'=>WS_PARAM_FORCE_ARRAY),
    125         ),
    126       'adds the elements to the caddie'
     145        'image_id'=> array('flags'=>WS_PARAM_FORCE_ARRAY,
     146                           'type'=>WS_TYPE_ID),
     147        ),
     148      '<b>Admin only.</b> Adds elements to the caddie. Returns the number of elements added.'
    127149    );
    128150
     
    130152      'pwg.categories.getImages',
    131153      'ws_categories_getImages',
    132       array(
    133         'cat_id' =>     array('default'=>0,
    134                               'flags'=>WS_PARAM_FORCE_ARRAY),
    135         'recursive' =>  array('default'=>false ),
    136         'per_page' =>   array('default'=>100,
    137                               'maxValue'=>$conf['ws_max_images_per_page']),
    138         'page' =>       array('default'=>0),
    139         'order' =>      array('default'=>null),
    140         'f_min_rate' => array('default'=>null),
    141         'f_max_rate' => array('default'=>null),
    142         'f_min_hit' =>  array('default'=>null),
    143         'f_max_hit' =>  array('default'=>null),
    144         'f_min_date_available' => array('default'=>null),
    145         'f_max_date_available' => array('default'=>null),
    146         'f_min_date_created' =>   array('default'=>null),
    147         'f_max_date_created' =>   array('default'=>null),
    148         'f_min_ratio' => array('default'=>null),
    149         'f_max_ratio' => array('default'=>null),
    150         'f_max_level' => array('default'=>null),
    151         ),
     154      array_merge(array(
     155        'cat_id' =>     array('default'=>null,
     156                              'flags'=>WS_PARAM_FORCE_ARRAY,
     157                              'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     158        'recursive' =>  array('default'=>false,
     159                              'type'=>WS_TYPE_BOOL),
     160        'per_page' =>   array('default'=>100,
     161                              'maxValue'=>$conf['ws_max_images_per_page'],
     162                              'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     163        'page' =>       array('default'=>0,
     164                              'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     165        'order' =>      array('default'=>null,
     166                              'info'=>'id, file, name, hit, rating_score, date_creation, date_available, random'),
     167        ), $f_params),
    152168      'Returns elements for the corresponding categories.
    153 <br><b>cat_id</b> can be empty if <b>recursive</b> is true. Can be sent as an array.
    154 <br><b>order</b> comma separated fields for sorting (file,id, rating_score,...)'
     169<br><b>cat_id</b> can be empty if <b>recursive</b> is true.
     170<br><b>order</b> comma separated fields for sorting'
    155171    );
    156172
     
    159175      'ws_categories_getList',
    160176      array(
    161         'cat_id' =>       array('default'=>0),
    162         'recursive' =>    array('default'=>false),
    163         'public' =>       array('default'=>false),
    164         'tree_output' =>  array('default'=>false),
    165         'fullname' =>     array('default'=>false),
    166         ),
    167       'retrieves a list of categories (tree_output option only compatible with json/php output format'
     177        'cat_id' =>       array('default'=>null,
     178                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE,
     179                                'info'=>'Parent category. "0" or empty for root.'),
     180        'recursive' =>    array('default'=>false,
     181                                'type'=>WS_TYPE_BOOL),
     182        'public' =>       array('default'=>false,
     183                                'type'=>WS_TYPE_BOOL),
     184        'tree_output' =>  array('default'=>false,
     185                                'type'=>WS_TYPE_BOOL),
     186        'fullname' =>     array('default'=>false,
     187                                'type'=>WS_TYPE_BOOL),
     188        ),
     189      'Returns a list of categories.'
    168190    );
    169191
     
    171193      'pwg.getMissingDerivatives',
    172194      'ws_getMissingDerivatives',
    173       array(
    174         'types' =>      array('default'=>array(),
    175                               'flags'=>WS_PARAM_FORCE_ARRAY),
    176         'ids' =>        array('default'=>array(),
    177                               'flags'=>WS_PARAM_FORCE_ARRAY),
    178         'max_urls' =>   array('default'=>200),
    179         'prev_page' =>  array('default'=>null),
    180         'f_min_rate' => array('default'=>null),
    181         'f_max_rate' => array('default'=>null),
    182         'f_min_hit' =>  array('default'=>null),
    183         'f_max_hit' =>  array('default'=>null),
    184         'f_min_date_available' => array('default'=>null),
    185         'f_max_date_available' => array('default'=>null),
    186         'f_min_date_created' =>   array('default'=>null),
    187         'f_max_date_created' =>   array('default'=>null),
    188         'f_min_ratio' => array('default'=>null),
    189         'f_max_ratio' => array('default'=>null),
    190         'f_max_level' => array('default'=>null),
    191         ),
    192       'retrieves a list of derivatives to build'
     195      array_merge(array(
     196        'types' =>        array('default'=>null,
     197                                'flags'=>WS_PARAM_FORCE_ARRAY,
     198                                'info'=>'square, thumb, 2small, xsmall, small, medium, large, xlarge, xxlarge'),
     199        'ids' =>          array('default'=>null,
     200                                'flags'=>WS_PARAM_FORCE_ARRAY,
     201                                'type'=>WS_TYPE_ID),
     202        'max_urls' =>     array('default'=>200,
     203                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     204        'prev_page' =>    array('default'=>null,
     205                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     206        ), $f_params),
     207      '<b>Admin only.</b> Returns a list of derivatives to build.'
    193208    );
    194209
     
    197212      'ws_images_addComment',
    198213      array(
    199         'image_id' => array(),
     214        'image_id' => array('type'=>WS_TYPE_ID),
    200215        'author' =>   array('default'=>is_a_guest()?'guest':$user['username']),
    201216        'content' =>  array(),
    202217        'key' =>      array(),
    203218        ),
    204       'add a comment to an image'
     219      '<b>POST only.</b> Adds a comment to an image.'
    205220    );
    206221
     
    209224      'ws_images_getInfo',
    210225      array(
    211         'image_id' =>           array(),
    212         'comments_page' =>      array('default'=>0 ),
    213         'comments_per_page' =>  array('default' =>  $conf['nb_comment_page'],
    214                                       'maxValue' => 2*$conf['nb_comment_page']),
    215         ),
    216       'retrieves information about the given photo'
     226        'image_id' =>           array('type'=>WS_TYPE_ID),
     227        'comments_page' =>      array('default'=>0,
     228                                      'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     229        'comments_per_page' =>  array('default'=>$conf['nb_comment_page'],
     230                                      'maxValue'=>2*$conf['nb_comment_page'],
     231                                      'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     232        ),
     233      'Returns information about an image.'
    217234    );
    218235
     
    220237      'pwg.images.rate',
    221238      'ws_images_rate',
    222       array('image_id', 'rate'),
    223       'rate the image'
     239      array(
     240        'image_id' => array('type'=>WS_TYPE_ID),
     241        'rate' =>     array('type'=>WS_TYPE_FLOAT),
     242      ),
     243      'Rates an image.'
    224244    );
    225245
     
    227247      'pwg.images.search',
    228248      'ws_images_search',
    229       array(
    230         'query' =>      array(),
    231         'per_page' =>   array('default'=>100,
    232                               'maxValue'=>$conf['ws_max_images_per_page']),
    233         'page' =>       array('default'=>0),
    234         'order' =>      array('default'=>null),
    235         'f_min_rate' => array('default'=>null),
    236         'f_max_rate' => array('default'=>null),
    237         'f_min_hit' =>  array('default'=>null),
    238         'f_max_hit' =>  array('default'=>null),
    239         'f_min_date_available' => array('default'=>null),
    240         'f_max_date_available' => array('default'=>null),
    241         'f_min_date_created' =>   array('default'=>null),
    242         'f_max_date_created' =>   array('default'=>null),
    243         'f_min_ratio' => array('default'=>null),
    244         'f_max_ratio' => array('default'=>null),
    245         'f_max_level' => array('default'=>null),
    246         ),
     249      array_merge(array(
     250        'query' =>        array(),
     251        'per_page' =>     array('default'=>100,
     252                                'maxValue'=>$conf['ws_max_images_per_page'],
     253                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     254        'page' =>         array('default'=>0,
     255                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     256        'order' =>        array('default'=>null,
     257                                'info'=>'id, file, name, hit, rating_score, date_creation, date_available, random'),
     258        ), $f_params),
    247259      'Returns elements for the corresponding query search.'
    248260    );
     
    252264      'ws_images_setPrivacyLevel',
    253265      array(
    254         'image_id' => array('flags'=>WS_PARAM_FORCE_ARRAY),
    255         'level' =>    array('maxValue'=>$conf['available_permission_levels']),
    256         ),
    257       'sets the privacy levels for the images (POST method only)'
     266        'image_id' => array('flags'=>WS_PARAM_FORCE_ARRAY,
     267                            'type'=>WS_TYPE_ID),
     268        'level' =>    array('maxValue'=>max($conf['available_permission_levels']),
     269                            'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     270        ),
     271      '<b>Admin & POST only.</b> Sets the privacy levels for the images.'
    258272    );
    259273
     
    261275      'pwg.images.setRank',
    262276      'ws_images_setRank',
    263       array('image_id', 'category_id', 'rank'),
    264       'sets the rank of a photo for a given album (POST method only, for admins)'
     277      array(
     278        'image_id'    => array('type'=>WS_TYPE_ID),
     279        'category_id' => array('type'=>WS_TYPE_ID),
     280        'rank'        => array('type'=>WS_TYPE_INT|WS_TYPE_POSITIVE|WS_TYPE_NOTNULL)
     281        ),
     282      '<b>Admin & POST only.</b> Sets the rank of a photo for a given album.'
    265283    );
    266284
     
    269287      'ws_rates_delete',
    270288      array(
    271         'user_id' =>      array(),
     289        'user_id' =>      array('type'=>WS_TYPE_ID),
    272290        'anonymous_id' => array('default'=>null),
    273291        ),
    274       'deletes all rates for a user (POST method only, admins only)'
     292      '<b>Admin & POST only.</b> Deletes all rates for a user.'
    275293    );
    276294
     
    279297      'ws_session_getStatus',
    280298      null,
    281       null
     299      'Gets information about the current session. Also provides a token useable with admin methods.'
    282300    );
    283301
     
    286304      'ws_session_login',
    287305      array('username', 'password'),
    288       'POST method only'
     306      '<b>POST only.</b> Tries to login the user.'
    289307    );
    290308
     
    293311      'ws_session_logout',
    294312      null,
    295       null
     313      'Ends the current session.'
    296314    );
    297315
     
    300318      'ws_tags_getList',
    301319      array(
    302         'sort_by_counter' => array('default' =>false),
    303         ),
    304       'retrieves a list of available tags'
     320        'sort_by_counter' => array('default'=>false,
     321                                   'type'=>WS_TYPE_BOOL),
     322        ),
     323      'Retrieves a list of available tags.'
    305324    );
    306325
     
    308327      'pwg.tags.getImages',
    309328      'ws_tags_getImages',
    310       array(
     329      array_merge(array(
    311330        'tag_id' =>       array('default'=>null,
    312                                 'flags'=>WS_PARAM_FORCE_ARRAY),
     331                                'flags'=>WS_PARAM_FORCE_ARRAY,
     332                                'type'=>WS_TYPE_ID),
    313333        'tag_url_name' => array('default'=>null,
    314334                                'flags'=>WS_PARAM_FORCE_ARRAY),
    315335        'tag_name' =>     array('default'=>null,
    316336                                'flags'=>WS_PARAM_FORCE_ARRAY),
    317         'tag_mode_and' => array('default'=>false),
     337        'tag_mode_and' => array('default'=>false,
     338                                'type'=>WS_TYPE_BOOL),
    318339        'per_page' =>     array('default'=>100,
    319                                 'maxValue'=>$conf['ws_max_images_per_page']),
    320         'page' =>         array('default'=>0),
    321         'order' =>        array('default'=>null),
    322         'f_min_rate' =>   array('default'=>null),
    323         'f_max_rate' =>   array('default'=>null),
    324         'f_min_hit' =>    array('default'=>null),
    325         'f_max_hit' =>    array('default'=>null),
    326         'f_min_date_available' => array('default'=>null),
    327         'f_max_date_available' => array('default'=>null),
    328         'f_min_date_created' =>   array('default'=>null),
    329         'f_max_date_created' =>   array('default'=>null),
    330         'f_min_ratio' => array('default'=>null),
    331         'f_max_ratio' => array('default'=>null),
    332         'f_max_level' => array('default'=>null),
    333         ),
    334       'Returns elements for the corresponding tags. Note that tag_id, tag_url_name, tag_name an be arrays. Fill at least one of them. '
     340                                'maxValue'=>$conf['ws_max_images_per_page'],
     341                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     342        'page' =>         array('default'=>0,
     343                                'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     344        'order' =>        array('default'=>null,
     345                                'info'=>'id, file, name, hit, rating_score, date_creation, date_available, random'),
     346        ), $f_params),
     347      'Returns elements for the corresponding tags. Fill at least tag_id, tag_url_name or tag_name.'
    335348    );
    336349
     
    338351      'pwg.images.addChunk',
    339352      'ws_images_add_chunk',
    340       array('data', 'original_sum', 'type', 'position'),
    341       'POST method only. For admin only.'
     353      array(
     354        'data' =>         array(),
     355        'original_sum' => array(),
     356        'type' =>         array('default'=>'file',
     357                                'info'=>'Must be "file", for backward compatiblity "high" and "thumb" are allowed.'),
     358        'position' =>     array()
     359        ),
     360      '<b>Admin & POST only.</b> Add a chunk of a file.'
    342361    );
    343362
     
    345364      'pwg.images.addFile',
    346365      'ws_images_addFile',
    347       array('image_id', 'type', 'sum'),
    348       'Add or update a file for an existing photo. pwg.images.addChunk must have been called  before (maybe several times)'
     366      array(
     367        'image_id' => array('type'=>WS_TYPE_ID),
     368        'type' =>     array('default'=>'file',
     369                            'info'=>'Must be "file", for backward compatiblity "high" and "thumb" are allowed.'),
     370        'sum' =>      array(),
     371        ),
     372      '<b>Admin only.</b> Add or update a file for an existing photo.
     373<br>pwg.images.addChunk must have been called before (maybe several times).'
    349374    );
    350375
     
    354379      'ws_images_add',
    355380      array(
    356         'file_sum' =>           array(),
    357381        'thumbnail_sum' =>      array('default'=>null),
    358382        'high_sum' =>           array('default'=>null),
    359383        'original_sum' =>       array(),
    360         'original_filename' =>  array('default'=>null),
     384        'original_filename' =>  array('default'=>null,
     385                                      'Provide it if "check_uniqueness" is true and $conf["uniqueness_mode"] is "filename".'),
    361386        'name' =>               array('default'=>null),
    362387        'author' =>             array('default'=>null),
    363388        'date_creation' =>      array('default'=>null),
    364389        'comment' =>            array('default'=>null),
    365         'categories' =>         array('default'=>null),
    366         'tag_ids' =>            array('default'=>null),
     390        'categories' =>         array('default'=>null,
     391                                      'info'=>'String list "category_id[,rank];category_id[,rank]".<br>The rank is optional and is equivalent to "auto" if not given.'),
     392        'tag_ids' =>            array('default'=>null,
     393                                      'info'=>'Comma separated ids'),
    367394        'level' =>              array('default'=>0,
    368                                       'maxValue'=>$conf['available_permission_levels']),
    369         'check_uniqueness' =>   array('default'=>true),
    370         'image_id' =>           array('default'=>null),
    371         ),
    372       'POST method only.
    373 <br><b>categories</b> is a string list "category_id[,rank];category_id[,rank]"
    374 The rank is optional and is equivalent to "auto" if not given.'
     395                                      'maxValue'=>max($conf['available_permission_levels']),
     396                                      'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
     397        'check_uniqueness' =>   array('default'=>true,
     398                                      'type'=>WS_TYPE_BOOL),
     399        'image_id' =>           array('default'=>null,
     400                                      'type'=>WS_TYPE_ID),
     401        ),
     402      '<b>Admin only.</b> Add an image.
     403<br>pwg.images.addChunk must have been called before (maybe several times).
     404<br>Don\'t use "thumbnail_sum" and "high_sum", these parameters are here for backward compatibility.'
    375405    );
    376406
     
    379409      'ws_images_addSimple',
    380410      array(
    381         'category' => array('default'=>null),
     411        'category' => array('default'=>null,
     412                            'flags'=>WS_PARAM_FORCE_ARRAY,
     413                            'type'=>WS_TYPE_ID),
    382414        'name' =>     array('default'=>null),
    383415        'author' =>   array('default'=>null),
    384416        'comment' =>  array('default'=>null),
    385417        'level' =>    array('default'=>0,
    386                             'maxValue'=>$conf['available_permission_levels']),
     418                            'maxValue'=>max($conf['available_permission_levels']),
     419                            'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
    387420        'tags' =>     array('default'=>null,
    388421                            'flags'=>WS_PARAM_ACCEPT_ARRAY),
    389         'image_id' => array('default'=>null),
    390         ),
    391       'POST method only.<br>Use the <b>image</b> field for uploading file.
    392 <br>Set the form encoding to "form-data"<br><b>category</b> is the numeric identifier of the destination category.
     422        'image_id' => array('default'=>null,
     423                            'type'=>WS_TYPE_ID),
     424        ),
     425      '<b>Admin & POST only.</b> Add an image.
     426<br>Use the <b>$_FILES[image]</b> field for uploading file.
     427<br>Set the form encoding to "form-data".
    393428<br>You can update an existing photo if you define an existing image_id.'
    394429    );
     
    398433      'ws_images_delete',
    399434      array(
    400         'image_id' =>   array('default'=>0),
     435        'image_id' =>   array('flags'=>WS_PARAM_ACCEPT_ARRAY),
    401436        'pwg_token' =>  array(),
    402437        ),
    403       'Delete photos. You can give several image_ids, comma separated'
     438      '<b>Admin & POST only.</b> Deletes image(s).'
    404439    );
    405440
     
    408443      'ws_categories_getAdminList',
    409444      null,
    410       'administration method only'
     445      '<b>Admin only.</b>'
    411446    );
    412447
     
    416451      array(
    417452        'name' =>         array(),
    418         'parent' =>       array('default'=>null),
     453        'parent' =>       array('default'=>null,
     454                                'type'=>WS_TYPE_ID),
    419455        'comment' =>      array('default'=>null),
    420         'visible' =>      array('default'=>null),
    421         'status' =>       array('default'=>null),
    422         'commentable' =>  array('default'=>'true'),
    423         ),
    424       'administration method only'
     456        'visible' =>      array('default'=>true,
     457                                'type'=>WS_TYPE_BOOL),
     458        'status' =>       array('default'=>null,
     459                                'info'=>'public, private'),
     460        'commentable' =>  array('default'=>true,
     461                                'type'=>WS_TYPE_BOOL),
     462        ),
     463      '<b>Admin only.</b> Adds an album.'
    425464    );
    426465
     
    429468      'ws_categories_delete',
    430469      array(
    431         'category_id'=>           array('default'=>0),
     470        'category_id'=>           array('flags'=>WS_PARAM_ACCEPT_ARRAY),
     471        'photo_deletion_mode' =>  array('default'=>'delete_orphans'),
    432472        'pwg_token' =>            array(),
    433         'photo_deletion_mode' =>  array('default'=>'delete_orphans'),
    434         ),
    435       'Delete categories. You can give several category_ids, comma separated.
     473        ),
     474      '<b>Admin & POST only.</b> Deletes album(s).
    436475<br><b>photo_deletion_mode</b> can be "no_delete" (may create orphan photos), "delete_orphans"
    437476(default mode, only deletes photos linked to no other album) or "force_delete" (delete all photos, even those linked to other albums)'
     
    442481      'ws_categories_move',
    443482      array(
    444         'category_id' =>  array('default'=>0),
    445         'parent' =>       array('default'=>0),
     483        'category_id' =>  array('flags'=>WS_PARAM_ACCEPT_ARRAY),
     484        'parent' =>       array('type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
    446485        'pwg_token' =>    array(),
    447486        ),
    448       'Move categories. You can give several category_ids, comma separated. Set parent as 0 to move to gallery root. Only virtual categories can be moved.'
     487      '<b>Admin & POST only.</b> Move album(s).
     488<br>Set parent as 0 to move to gallery root. Only virtual categories can be moved.'
    449489    );
    450490
     
    453493      'ws_categories_setRepresentative',
    454494      array(
    455         'category_id' =>  array('default'=>0),
    456         'image_id' =>     array('default'=>0),
    457         ),
    458       'Set the representative photo for an album. The photo doesn\'t have to belong to the album. POST method only. Administration method only.'
     495        'category_id' =>  array('type'=>WS_TYPE_ID),
     496        'image_id' =>     array('type'=>WS_TYPE_ID),
     497        ),
     498      '<b>Admin & POST only.</b> Sets the representative photo for an album. The photo doesn\'t have to belong to the album.'
    459499    );
    460500
     
    463503      'ws_tags_getAdminList',
    464504      null,
    465       'administration method only'
    466     );
    467 
    468   $service->addMethod(
     505      '<b>Admin only.</b> '
     506    );
     507
     508  $service->addMethod( // TODO: create multiple tags
    469509      'pwg.tags.add',
    470510      'ws_tags_add',
    471511      array('name'),
    472       'administration method only'
     512      '<b>Admin only.</b> Adds a new tag.'
    473513    );
    474514
     
    480520        'filename_list' =>  array('default'=>null),
    481521        ),
    482       'check existence of a photo list'
     522      '<b>Admin only.</b>  Checks existence of images.
     523<br>Give <b>md5sum_list</b> if $conf[uniqueness_mode]==md5sum. Give <b>filename_list</b> if $conf[uniqueness_mode]==filename.'
    483524    );
    484525
     
    487528      'ws_images_checkFiles',
    488529      array(
    489         'image_id' =>       array(),
     530        'image_id' =>       array('type'=>WS_TYPE_ID),
     531        'file_sum' =>       array('default'=>null),
    490532        'thumbnail_sum' =>  array('default'=>null),
    491         'file_sum' =>       array('default'=>null),
    492533        'high_sum' =>       array('default'=>null),
    493534        ),
    494       'check if you have updated version of your files for a given photo, for each requested file type, the answer can be "missing", "equals" or "differs"'
     535      '<b>Admin only.</b> Checks if you have updated version of your files for a given photo, the answer can be "missing", "equals" or "differs".
     536<br>Don\'t use "thumbnail_sum" and "high_sum", these parameters are here for backward compatibility.'
    495537    );
    496538
     
    499541      'ws_images_checkUpload',
    500542      null,
    501       'check if Piwigo is ready for upload'
     543      '<b>Admin only.</b> Checks if Piwigo is ready for upload.'
    502544    );
    503545
     
    506548      'ws_images_setInfo',
    507549      array(
    508         'image_id' =>       array(),
     550        'image_id' =>       array('type'=>WS_TYPE_ID),
    509551        'file' =>           array('default'=>null),
    510552        'name' =>           array('default'=>null),
     
    512554        'date_creation' =>  array('default'=>null),
    513555        'comment' =>        array('default'=>null),
    514         'categories' =>     array('default'=>null),
    515         'tag_ids' =>        array('default'=>null),
     556        'categories' =>     array('default'=>null,
     557                                  'info'=>'String list "category_id[,rank];category_id[,rank]".<br>The rank is optional and is equivalent to "auto" if not given.'),
     558        'tag_ids' =>        array('default'=>null,
     559                                  'info'=>'Comma separated ids'),
    516560        'level' =>          array('default'=>null,
    517                                   'maxValue'=>$conf['available_permission_levels']),
     561                                  'maxValue'=>max($conf['available_permission_levels']),
     562                                  'type'=>WS_TYPE_INT|WS_TYPE_POSITIVE),
    518563        'single_value_mode' =>    array('default'=>'fill_if_empty'),
    519564        'multiple_value_mode' =>  array('default'=>'append'),
    520565        ),
    521       'POST method only. Admin only
    522 <br><b>categories</b> is a string list "category_id[,rank];category_id[,rank]" The rank is optional and is equivalent to "auto" if not given.
     566      '<b>Admin & POST only.</b> Changes properties of an image.
    523567<br><b>single_value_mode</b> can be "fill_if_empty" (only use the input value if the corresponding values is currently empty) or "replace"
    524 (overwrite any existing value) and applies to single values properties like name/author/date_creation/comment
    525 <br><b>multiple_value_mode</b> can be "append" (no change on existing values, add the new values) or "replace" and applies to multiple values properties like tag_ids/categories'
     568(overwrite any existing value) and applies to single values properties like name/author/date_creation/comment.
     569<br><b>multiple_value_mode</b> can be "append" (no change on existing values, add the new values) or "replace" and applies to multiple values properties like tag_ids/categories.'
    526570    );
    527571
     
    530574      'ws_categories_setInfo',
    531575      array(
    532         'category_id' =>  array(),
     576        'category_id' =>  array('type'=>WS_TYPE_ID),
    533577        'name' =>         array('default'=>null),
    534578        'comment' =>      array('default'=>null),
    535579        ),
    536       'POST method only.'
     580      '<b>Admin & POST only.</b> Changes properties of an album.'
    537581    );
    538582 
     
    541585      'ws_plugins_getList',
    542586      null,
    543       'Admin only
    544 <br>get the list of plugin with id, name, version, state and description'
     587      '<b>Admin only.</b> Gets the list of plugins with id, name, version, state and description.'
    545588    );
    546589
     
    548591      'pwg.plugins.performAction',
    549592      'ws_plugins_performAction',
    550       array('action', 'plugin', 'pwg_token'),
    551       'Admin only
    552 <br>install/activate/deactivate/uninstall/delete a plugin'
     593      array(
     594        'action'    => array('info'=>'install, activate, deactivate, uninstall, delete'),
     595        'plugin'    => array(),
     596        'pwg_token' => array(),
     597        ),
     598      '<b>Admin only.</b>'
    553599    );
    554600
     
    556602      'pwg.themes.performAction',
    557603      'ws_themes_performAction',
    558       array('action', 'theme', 'pwg_token'),
    559       'activate/deactivate/delete/set_default a theme<br>administration status required'
     604      array(
     605        'action'    => array('info'=>'activate, deactivate, delete, set_default'),
     606        'theme'     => array(),
     607        'pwg_token' => array(),
     608        ),
     609      '<b>Admin only.</b>'
    560610    );
    561611
     
    563613      'pwg.extensions.update',
    564614      'ws_extensions_update',
    565       array('type', 'id', 'revision', 'pwg_token'),
    566       'Update an extension. Webmaster only.
    567 <br>Parameter type must be "plugins", "languages" or "themes".'
     615      array(
     616        'type' => array('info'=>'plugins, languages, themes'),
     617        'id' => array(),
     618        'revision' => array(),
     619        'pwg_token' => array(),
     620        ),
     621      '<b>Webmaster only.</b>'
    568622  );
    569623
     
    572626      'ws_extensions_ignoreupdate',
    573627      array(
    574         'type' =>       array('default'=>null),
     628        'type' =>       array('default'=>null,
     629                              'info'=>'plugins, languages, themes'),
    575630        'id' =>         array('default'=>null),
    576         'reset' =>      array('default'=>null),
     631        'reset' =>      array('default'=>false,
     632                              'type'=>WS_TYPE_BOOL,
     633                              'info'=>'If true, all ignored extensions will be reinitilized.'),
    577634        'pwg_token' =>  array(),
    578635      ),
    579       'Ignore an extension if it need update.
    580 <br>Parameter type must be "plugins", "languages" or "themes".
    581 <br>If reset parameter is true, all ignored extensions will be reinitilized.'
     636      '<b>Webmaster only.</b> Ignores an extension if it needs update.'
    582637  );
    583638
     
    586641      'ws_extensions_checkupdates',
    587642      null,
    588       'Check if piwigo or extensions are up to date.'
     643      '<b>Admin only.</b> Checks if piwigo or extensions are up to date.'
    589644  );
    590645}
Note: See TracChangeset for help on using the changeset viewer.