Merge pull request rackspace#603 from kaecyra/improve-list-ports-docs

Add more verbose annotation to `listPorts` to clarify filtering options

Author: Jamie Hannaford

doc/services/networking/ports.rst

@@ -86,6 +86,21 @@ You can list all the ports to which you have access as shown in the following ex
 
 `Get the executable PHP script for this example <https://raw.githubusercontent.com/rackspace/php-opencloud/master/samples/Networking/list-ports.php>`_
 
+The port list query may be filtered by numerous optional parameters as per the `API documentation <http://developer.openstack.org/api-ref-networking-v2.html#listPorts>`_
+
+.. code-block:: php
+
+  $ports = $networkingService->listPorts([
+      'status' => 'ACTIVE',
+      'device_id' => '9ae135f4-b6e0-4dad-9e91-3c223e385824'
+  ]);
+
+  foreach ($ports as $port) {
+      /** @var $port OpenCloud\Networking\Resource\Port **/
+  }
+
+`Get the executable PHP script for this example <https://raw.githubusercontent.com/rackspace/php-opencloud/master/samples/Networking/list-ports-filtered.php>`_
+
 
 Get a port
 ----------

samples/Networking/list-ports-filtered.php

@@ -0,0 +1,39 @@
+<?php
+/**
+ * Copyright 2012-2014 Rackspace US, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+require dirname(__DIR__) . '/../vendor/autoload.php';
+
+use OpenCloud\Rackspace;
+
+// 1. Instantiate a Rackspace client. You can replace {authUrl} with
+// Rackspace::US_IDENTITY_ENDPOINT or similar
+$client = new Rackspace('{authUrl}', array(
+    'username' => '{username}',
+    'apiKey'   => '{apiKey}',
+));
+
+// 2. Obtain a Networking service object from the client.
+$networkingService = $client->networkingService(null, '{region}');
+
+// 3. List ACTIVE ports for given device ID
+$ports = $networkingService->listPorts([
+    'status' => 'ACTIVE',
+    'device_id' => '{deviceId}'
+]);
+foreach ($ports as $port) {
+    /** @var $port OpenCloud\Networking\Resource\Port **/
+}