[API] TS3 PHP Framework

[ScP]

The subChannelList() method which can be called on a TeamSpeak3_Node_Channel object is just for convenience.

[Glotzkowski]

realy good work

THX

[ScP]

Does anyone have any feedback regarding the serverGroupIdentify() method? Read my previous posting for details.

[kasebone]

works great on my installation, but its very basic like the default set. :-)

[theeggman]

Works here too, but I also have a pretty standard group setup.

[ScP]

I'm pleased to announce that the next official update of the TS3 PHP Framework will be released as soon as the upcoming version of the TeamSpeak 3 Server (3.0.0-beta25) is available to the public. At this point I'll also reopen the original forum thread with a detailed project description. As a small preview, I've uploaded the latest version of the included example pages which already contain some of the new features:

http://www.planetteamspeak.com/demos...work/examples/

Here's the latest changelog:

===============================================================================
                        TS 3 PHP Framework - Changelog
                          Copyright Planet TeamSpeak
                        http://www.planetteamspeak.com
===============================================================================
   + Added feature or noticable improvement
   - Bug fix or something removed
   * Changed or Information
   ! Important - Take note!
===============================================================================

=== Release 1.0.28-beta - ?? Jun 2010 ===
 ! upgrading your servers to 3.0.0-beta25 (build >= 11255) is mandatory
 + added TeamSpeak3_Node_Server::isOffline()
 * TeamSpeak3_Node_Server::serverGroupCreate() now supports type parameter
 * TeamSpeak3_Node_Server::channelGroupCreate() now supports type parameter
 * TeamSpeak3_Viewer_Html interface now supports downloading of remote icons
 ! please keep in mind that the TeamSpeak3_Viewer_Html interface is intended 
   as a proof of concept application and should be modified to cache remote 
   icons before beeing used in a production environment
 - fixed invalid command name in TeamSpeak3_Node_Server::clientDeleteDb()
 - removed check for client_flag_talking in TeamSpeak3_Node_Client::getIcon()

=== Release 1.0.27-beta - 24 May 2010 ===
 ! upgrading your servers to 3.0.0-beta23 (build >= 11062) is mandatory
 ! TeamSpeak3_Adapter_Abstract::__construct() now expects an array of options
   instead of a TeamSpeak3_Transport_Abstract object
 + added TeamSpeak3_Adapter_Update
 + added TeamSpeak3_Adapter_Blacklist
 + added TeamSpeak3_Transport_UDP
 + added TeamSpeak3_Adapter_Abstract::initTransport()
 + added TeamSpeak3_Node_Abstract::getClass()
 + added TeamSpeak3_Node_Abstract::serverGroupIdentify() (WIP)
 - fixed invalid return value in TeamSpeak3_Helper_String::resize()
 * TeamSpeak3::autoload() no longer loads libraries without the TeamSpeak3
   classname prefix to resolve issues with spl_autoload() implementations from
   other frameworks
 * TeamSpeak3_Viewer_Html interface now adds custom HTML class properties to 
   nodes to improve CSS customization options
 * TeamSpeak3_Viewer_Html interface now recognizes channel spacers (WIP)
 * internal release only

=== Release 1.0.26-beta - 14 Apr 2010 ===
 ! codebase converted to Zend Studio 7.1.2 project
 + added TeamSpeak3_Node_Server::channelIsSpacer() 
 + added TeamSpeak3_Node_Server::channelSpacerCreate()
 + added TeamSpeak3_Node_Server::channelSpacerGetType()
 + added constants for different channel spacer types (WIP)
 - fixed unused parameters in TeamSpeak3_Node_Channel::permRemove()
 - fixed unused parameters in TeamSpeak3_Node_Server::channelFileRename()
 * TeamSpeak3_Helper_String::contains() now supports RegExp patterns and is
   case-insensitive
 * lists generated by TeamSpeak3_Node_Server::channelFileList() are now sorted 
   by filename
 * TeamSpeak3_Viewer_Html interface now calculates server uptime correctly
 * changed examples to include new features
 * internal release only

=== Release 1.0.25-beta - 1 Apr 2010 ===
 ! upgrading your servers to 3.0.0-beta21 (build >= 10608) is mandatory
 + added TeamSpeak3_Exception::registerCustomMessage()
 + added TeamSpeak3_Exception::unregisterCustomMessage()
 + added TeamSpeak3_Helper_Convert::groupType()
 + added TeamSpeak3_Helper_Convert::permissionType()
 + added TeamSpeak3_Helper_Convert::password()
 + added TeamSpeak3_Helper_String::filterAlnum()
 + added TeamSpeak3_Helper_String::filterAlpha()
 + added TeamSpeak3_Helper_String::filterDigits()
 + added constants for different group auto-update types
 - changed invalid variable name in TeamSpeak3_Adapter_ServerQuery::request()
 * TeamSpeak3_Adapter_FileTransfer::download() now supports fpassthru() to
   write the results to the PHP output buffer which can be very useful when 
   transferring large files
 * TeamSpeak3_Helper_Convert::seconds() now supports custom output format
 * internal release only

=== Release 1.0.24-beta - 24 Feb 2010 ===
 ! upgrading your servers to 3.0.0-beta19 (build >= 10368) is mandatory
 + added TeamSpeak3_Node_Abstract::iconIsLocal()
 + added TeamSpeak3_Node_Abstract::iconGetName()
 + added TeamSpeak3_Node_Server::iconDownload()
 + added TeamSpeak3_Node_Server::iconUpload()
 + added TeamSpeak3_Node_Channel::iconDownload()
 + added TeamSpeak3_Node_Client::iconDownload()
 + added TeamSpeak3_Node_Servergroup::iconDownload()
 + added TeamSpeak3_Node_Channelgroup::iconDownload()
 * TeamSpeak3_Transport_TCP methods will now read and write in small packets
   of 4096 bytes
 * TeamSpeak3_Node_Server snapshot methods now support three different export
   formats (SNAPSHOT_STRING, SNAPSHOT_BASE64, SNAPSHOT_HEXDEC)
 * internal release only

=== Release 1.0.23-beta - 28 Jan 2010 ===
 ! upgrading your servers to 3.0.0-beta17 (build >= 10036) is mandatory
 + added TeamSpeak3_Node_Server::customInfo()
 + added TeamSpeak3_Node_Client::customInfo()
 + added priority speaker information to TeamSpeak3_Viewer_Html interface
 * changed fetch mode from toAssocArray() to toArray() in several methods
 * spl_autoload_register() is only called once even if TeamSpeak3::init() is
   called multiple times
 - changed invalid variable name in TeamSpeak3_Node_Server::clientGetByUid()
 - changed invalid description for TeamSpeak3_Node_Client::remServerGroup()
 
=== Release 1.0.22-beta - 18 Jan 2010 ===
 ! library now requires PHP version 5.2.1 or newer
 ! upgrading your servers to 3.0.0-beta13 (build >= 9802) is mandatory
 + added TeamSpeak3_Adapter_Abstract::getProfiler()
 + added TeamSpeak3_Adapter_ServerQuery::getQueryCount()
 + added TeamSpeak3_Adapter_ServerQuery::getQueryRuntime()
 + added TeamSpeak3_Node_Server::customSearch()
 * adapter classes will now start their own timer for profiling
 * added "-times" to default clientList() parameters
 * added optional command parameters "tokendescription" and "tokencustomset" 
   to TeamSpeak3_Node_Server::tokenCreate()
 - fixed error exception in TeamSpeak3_Adapter_ServerQuery destructor
 - removed undefined variable in TeamSpeak3_Node_Server::channelFileRename()

=== Release 1.0.21-beta - 10 Jan 2010 ===
 ! all thrown TeamSpeak 3 Server error exceptions are now of objects of type
   TeamSpeak3_Adapter_ServerQuery_Exception
 ! TeamSpeak3_Node_Abstract::offsetSet() is now a wrapper for the modify() 
   method to allow direct modifications of node properties
 + added TeamSpeak3_Helper_Convert::codec()
 + added TeamSpeak3_Node_Abstract::toArray()
 + added TeamSpeak3_Node_Abstract::toString()
 + added TeamSpeak3_Node_Server::clientCount()
 + added TeamSpeak3_Node_Server::clientListDb()
 + added TeamSpeak3_Node_Server::clientFind()
 + added TeamSpeak3_Node_Server::clientFindDb()
 + added TeamSpeak3_Node_Host::setPredefinedQueryName()
 + added TeamSpeak3_Node_Host::setExcludeQueryClients()
 + added optional "timeout" parameter to TeamSpeak3::factory()
 + added optional "nickname" parameter to TeamSpeak3::factory()
 * error exception messages thrown by TeamSpeak3_Transport_TCP::connect()
   will be UTF-8 encoded
 * set some fancy titles in TeamSpeak3_Viewer_Html interface
 * tweaked some of the implemented RecursiveIterator methods
 * using strtr() instead of str_replace() in TeamSpeak3_Helper_String::arg()
 * isset($node) no longer queries node information automatically
 - fixed error exception when trying to start profiler timer twice
 - fixed invalid node list format after reset
 
=== Release 1.0.20-beta - 08 Jan 2010 ===
 ! factory URI now supports #no_query_clients fragment to remove ServerQuery
   clients from client lists and viewers
 + added TeamSpeak3_Helper_Profiler
 + added TeamSpeak3_Helper_Convert (WIP)
 - fixed unnessesary command requests on empty list caches
 - fixed recursion bug on empty virtual servers

=== Release 1.0.19-beta - 07 Jan 2010 ===
 + added TeamSpeak3_Adapter_Abstract::getTransportHost()
 + added TeamSpeak3_Adapter_Abstract::getTransportPort()
 + added TeamSpeak3_Node_Host::getAdapterHost()
 + added TeamSpeak3_Node_Host::getAdapterPort()
 + added TeamSpeak3_Node_Server::snapshotCreate()
 + added TeamSpeak3_Node_Server::snapshotDeploy()
 + added TeamSpeak3_Node_Server::selfPermOverview()
 * given parameter strings will be UTF-8 encoded while commands are prepared
 * TeamSpeak3_Node_Host::__toString() now returns hostname or IPv4 address
   instead of "TeamSpeak 3 Host"
 * public beta release

=== Release 1.0.18-beta - 06 Jan 2010 ===
 ! added code examples
 ! added online docs (http://docs.planetteamspeak.com/ts3/php/framework/)
 + added TeamSpeak3_Node_Client::avatarGetName()
 + added TeamSpeak3_Node_Client::avatarDownload()
 + added TeamSpeak3_Node_Client::permOverview()
 * TeamSpeak3_Viewer_Html constructor now supports custom image paths
 * whoami cache will be updated when creating temporary channels
 * whoami cache will be updated when moving own client
 - fixed "already member of channel" issue when sending two text messages to
   the same channel
 - ServerQuery adapter no longer tries to quit in desctructor when transport 
   is not connected
 - replaced invalid data types in method descriptions

=== Release 1.0.17-beta - 05 Jan 2010 ===
 * internal beta release

As always, I appreciate your feedback!

[theeggman]

Got a couple questions about the framework, I think here is the best place to ask them..

first.. Does the Framework require a certain version of php? On my production server I run version 5.2.6 as fast cgi (via ngnix) and on my development environment I'm using 5.3.2 (via mod_php and apache2). Version 1.0.22-beta works fine in both environments, but version 1.0.27-beta (the internal release posted here) does not render the html viewer on my production server. I cannot see any errors either, I'm a tad puzzled as to what is going on.

second... I noticed the tsviewer.com (this site uses your framework) website's scanner registers itself with a name so it does not connect as serveradmin from *****.. I'm wondering how I can do that in my own code... any advice would be great!

lastly - a small bug I noticed, not sure what is happening here either, but I have the examples (1.0.27-beta) working on my production server. I noticed when I looked at the example that views the server's information its reporting my server is on the blacklist, when clearly its not (I verified with a support ticket as well). Reports fine on my development server.. Maybe again has to do with my version of php?

[ScP]

Does the Framework require a certain version of php?

The minimum PHP version required by the framework is 5.2.1.

I noticed the tsviewer.com (this site uses your framework) website's scanner registers itself with a name so it does not connect as serveradmin from *****.. I'm wondering how I can do that in my own code... any advice would be great!

Simply. You can either call the setPredefinedQueryName() method on any node object or add the nickname parameter to the factory to set a custom nickname.

$ts3_ServerInstance = TeamSpeak3::factory("serverquery://user:pass@host:port/?nickname=Hello"); 

lastly - a small bug I noticed, not sure what is happening here either, but I have the examples (1.0.27-beta) working on my production server. I noticed when I looked at the example that views the server's information its reporting my server is on the blacklist, when clearly its not (I verified with a support ticket as well). Reports fine on my development server.. Maybe again has to do with my version of php?

I think this is a bug, but I doubt that it's related to your PHP version. What's the IP address of your server? I'd like to reproduce this issue on my end.

[theeggman]

Thank you for answering my questions.

What's the IP address of your server? I'd like to reproduce this issue on my end.

My server's ip is.. ts3.eggy.cc (67.220.68.53) though if you need query access I'll need to whitelist the ip you plan to test from..

Hrm.. what makes things more strange is if I run my code through my server's php-cli, it outputs the correct html and no php errors. I guess its something strange with ngnix and this new library version

[ScP]

My server's ip is.. ts3.eggy.cc (67.220.68.53) though if you need query access I'll need to whitelist the ip you plan to test from...

I tried to reproduce the issue on my end, but the blacklist server is reporting that your IP address is not blacklisted as expected.

I was using this code:

$status = TeamSpeak3::factory("blacklist")->isBlacklisted("ts3.eggy.cc");

TeamSpeak3::dump($status); 

Please test this on your server and tell me what the result is.

[theeggman]

I tried to reproduce the issue on my end, but the blacklist server is reporting that your IP address is not blacklisted as expected.

I was using this code:

$status = TeamSpeak3::factory("blacklist")->isBlacklisted("ts3.eggy.cc");

TeamSpeak3::dump($status); 

Please test this on your server and tell me what the result is.

Heh - On my Development environment, it returns the expected result. But in the (stubborn) production environment.. it returns true... Puzzling, perhaps Debian's build of php-cgi is bugged..

[ScP]

I guess I've got a slight idea of what could be the problem. Let me run some tests here and I'll send you a snapshot of the library later so you can retry this.

[theeggman]

I guess I've got a slight idea of what could be the problem. Let me run some tests here and I'll send you a snapshot of the library later so you can retry this.

Sounds good to me

[empi89]

hi scp,

first: your library is really nice! But the performance when you list all virtualservers on a host is bad. I call the Host->serverlist and will receive an array with server-objects. If I want some basic information I have to call the getinfo-method to fetch the nodeinfo. Well getinfo (server->fetchnodeinfo) will call serverinfo and fetch all server-information which is quite slow for hundreds of servers. for a simple serverlist not all the serverinfos are required. serverlist returns some basic information (id, port, status, clients, maxclients, uptime, name, autostart, unique_id) and this information is saved in the server-objects but not accessible via a method. It would help if you can make this properties accessible via an additional public method like getCachedInfo or getBasicInfo which will only return the actual nodeinfo.

I hope you can understand my problem and can add such a method to the public api. We're already using a simple method to return the nodeinfo but it's not very nice to depend on a non-standard-api in case of updates.

[ScP]

I'm using PHPs ArrayAccess interface to provide access to the simple node properties. Here's an example:

// echo virtualserver_name
echo $server;

// echo virtualserver_maxclients
echo $server['virtualserver_maxclients']; 

If you're trying to access a property which is currently not "known" by the object (e.g. not requested yet), the library will automatically call the appropriate ServerQuery command automatically to "extend" the information with all the details available.

So basically, as long as you only access properties which are available in the serverlist output, the lib will not query the serverinfo.

Note that when a virtual server is offline, the serverlist output will NOT contain the current number of clients online on this server - the property is missing which will cause the lib to query the serverinfo anyway...