[prev in list] [next in list] [prev in thread] [next in thread]
List: pear-doc
Subject: [PEAR-DOC] cvs: peardoc /en/package webservices.xml /en/package/webservices services-blogging.xml
From: "Christian Weiske" <cweiske () php ! net>
Date: 2007-04-15 10:16:40
Message-ID: cvscweiske1176632200 () cvsserver
[Download RAW message or body]
cweiske Sun Apr 15 10:16:40 2007 UTC
Added files:
/peardoc/en/package/webservices services-blogging.xml
/peardoc/en/package/webservices/services-blogging connecting.xml
drivers.xml
example.xml
intro.xml
posts.xml
Modified files:
/peardoc/en/package webservices.xml
Log:
Adding documentation for Services_Blogging
["cweiske-20070415101640.txt" (text/plain)]
http://cvs.php.net/viewvc.cgi/peardoc/en/package/webservices.xml?r1=1.18&r2=1.19&diff_format=u
Index: peardoc/en/package/webservices.xml
diff -u peardoc/en/package/webservices.xml:1.18 \
peardoc/en/package/webservices.xml:1.19
--- peardoc/en/package/webservices.xml:1.18 Tue Mar 27 15:06:40 2007
+++ peardoc/en/package/webservices.xml Sun Apr 15 10:16:39 2007
@@ -1,4 +1,4 @@
-<!-- $Revision: 1.18 $ -->
+<!-- $Revision: 1.19 $ -->
<chapter id="package.webservices">
@@ -7,6 +7,7 @@
&blankpagehack;
+ &package.webservices.services-blogging;
&package.webservices.services-delicious;
&package.webservices.services-ebay;
&package.webservices.services-technorati;
http://cvs.php.net/viewvc.cgi/peardoc/en/package/webservices/services-blogging.xml?view=markup&rev=1.1
Index: peardoc/en/package/webservices/services-blogging.xml
+++ peardoc/en/package/webservices/services-blogging.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect1 id="package.webservices.services-blogging">
<title>Services_Blogging</title>
<para>
Generic driver-based package to post and read blog entries.
</para>
&package.webservices.services-blogging.intro;
&package.webservices.services-blogging.connecting;
&package.webservices.services-blogging.drivers;
&package.webservices.services-blogging.posts;
&package.webservices.services-blogging.example;
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=webservices fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/peardoc/en/package/webservices/services-blogging/connecting.xml?view=markup&rev=1.1
Index: peardoc/en/package/webservices/services-blogging/connecting.xml
+++ peardoc/en/package/webservices/services-blogging/connecting.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect2 id="package.webservices.services-blogging.connecting">
<title>Connecting your blog server</title>
<para>
To post entries to your blog, you first need to obtain an instance of
the <classname>Services_Blogging_Driver</classname> suitable for your blog.
You need to either find out which API your blog system supports,
or let <classname>Services_Blogging</classname> magically autodiscover
those settings.
</para>
<para>
Creating a driver is done using <classname>Services_Blogging</classname>'s
<function>factory</function> method. It requires five parameters: The
driver name, username, password, server URL and the path of the API on the
server.
</para>
<example>
<title>Instantiating a driver using Services_Blogging::factory()</title>
<programlisting role="php"><![CDATA[
require_once 'Services/Blogging.php';
$bl = Services_Blogging::factory(
'metaWeblog', //driver name
'username',
'password',
'http://blog.example.com',
'/xmlrpc.php'
);
]]></programlisting>
</example>
<para>
Some blog drivers don't need server and path variables, just fill in
<literal>null</literal> in this case.
</para>
<sect3>
<title>Autodiscovering settings</title>
<para>
Since it can be tedious to find out which settings are needed for your
own blog, this package has a feature called autodiscovery. You either
can automatically detect the settings needed to create an instance of
the driver needed, or let the class automatically detect and return
an instance of the driver needed for your blog system.
</para>
<para>
Autodiscovering the settings of your blog can be done via
<classname>Services_Blogging</classname>'s
<function>discoverSettings</function>, passing the URL
of your blog as only parameter. It returns an array with all the needed
settings.
</para>
<para>
Most of the blogging softwares today support multiple blogging APIs. After
getting a list of supported APIs via autodiscovery, you need to choose which
one fits you best; it's usually the one supporting the most features.
<classname>Services_Blogging</classname> also helps you with this task by
providing a method called <function>getBestAvailableDriver</function>, just
passing the array of recently discovered settings to it. Now you have all
data needed to instantiate the driver itself.
</para>
<example>
<title>Auto-discovering settings</title>
<programlisting role="php"><![CDATA[
require_once 'Services/Blogging.php';
$settings = Services_Blogging::discoverSettings('http://blog.example.com');
var_dump($settings);
echo Services_Blogging::getBestAvailableDriver($settings) . "\r\n";
//go on with factory()
]]></programlisting>
</example>
<para>
If that all is still too much work for you, you can let do
<classname>Services_Blogging</classname> everything by calling
<function>discoverDriver</function>, passing the URL of your blog, your
username and password to it. It returns a the driver object.
</para>
<example>
<title>Creating a driver automatically</title>
<programlisting role="php"><![CDATA[
require_once 'Services/Blogging.php';
$bl = Services_Blogging::discoverDriver(
'http://blog.example.com',
'username',
'password'
);
]]></programlisting>
</example>
<note>
<para>
The autodiscovery methods throw an exception of type
<classname>Services_Blogging_Exception</classname> if something
goes wrong (either autodiscovery fails because your blog software does
not support it, or there is no suitable driver for your blog).
</para>
</note>
</sect3>
</sect2>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=webservices fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/peardoc/en/package/webservices/services-blogging/drivers.xml?view=markup&rev=1.1
Index: peardoc/en/package/webservices/services-blogging/drivers.xml
+++ peardoc/en/package/webservices/services-blogging/drivers.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect2 id="package.webservices.services-blogging.drivers">
<title>Drivers</title>
<para>
Due to the difference of features in the existing blogging APIs, there are
two driver classes: <classname>Services_Blogging_Driver</classname> and
<classname>Services_Blogging_ExtendetDriver</classname> (which extends the
first).
</para>
<para>
Drivers extending <classname>Services_Blogging_Driver</classname> do only
support creating, saving and deleting posts. They are not able to list
(or modify) existing posts.
</para>
<para>
Drivers extending from <classname>Services_Blogging_ExtendetDriver</classname>
do have more features: Reading existing posts, get a list of recent posts,
and getting a list of the titles of the recent posts.
</para>
</sect2>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=webservices fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/peardoc/en/package/webservices/services-blogging/example.xml?view=markup&rev=1.1
Index: peardoc/en/package/webservices/services-blogging/example.xml
+++ peardoc/en/package/webservices/services-blogging/example.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect2 id="package.webservices.services-blogging.example">
<title>Example</title>
<example>
<title>Posting an entry</title>
<programlisting role="php"><![CDATA[
<?php
require_once 'Services/Blogging.php';
$bl = Services_Blogging::factory(
'metaWeblog',
'username', 'password',
'http://blog.example.com', '/xmlrpc.php'
);
$post = $bl->createNewPost();
//$post->setId('14');
$post->title = 'Modified post title';
$post->content = "This is a modified test post by"
. " Services_Blogging\r\n\r\nSecond line\r\nThird one";
$post->categories = array('cat1', 'cat3');
$bl->savePost($post);
$nLastPostId = $post->id;
echo 'post id: ' . $nLastPostId . "\r\n";
//$bl->deletePost(17);
var_dump($bl->getPost($nLastPostId));
var_dump($bl->getRecentPostTitles(2));
var_dump($bl->getRecentPosts());
?>
]]></programlisting>
</example>
</sect2>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=webservices fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/peardoc/en/package/webservices/services-blogging/intro.xml?view=markup&rev=1.1
Index: peardoc/en/package/webservices/services-blogging/intro.xml
+++ peardoc/en/package/webservices/services-blogging/intro.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect2 id="package.webservices.services-blogging.intro">
<title>Introduction to Services_Blogging</title>
<para>
Weblogs are an important part of the internet: They allow normal
people to express their opinions and thoughts to their family, friends
and the whole world by simply publishing some text on a server. This
process is very easy and you don't need a grade in computer science to
even host a blog on your own or a rented server.
</para>
<para>
One drawback of blog software is mostly their user interface: Since it is
browser based, it requires you to be either online all the time while writing
your blog post, or write it in a normal text editor and copy&paste it
when going online. Using a text editor you cannot apply font styles to your
text.. An offline tool to write blog entries would be really nice in this
case.
</para>
<para>
Considering the idea of an offline tool for writing blog entries leads to
the availability of access to your blog from outside the normal web interface
- e.g via web services. Most blog hosters and blogging software packages
have support for such a web services API, mostly via XML-RPC.
</para>
<para>
Unfortunately, there are many different of these application programming
interfaces in the wild. Some of them support only posting of blog entries,
other ones also allow reading. Some blog softwares support images and tags
in their posts, others not. The variety is large, and so you could end up
writing custom code for every blog server you want to access because of the
differences in their API.
</para>
<para>
This is the point at which <classname>Services_Blogging</classname> comes into
play: It provides a unified API to post and read blog entries, independent of
the API supported by the server software hosting the blog. It uses a
driver-based approach to communicate with different APIs out there.
If a new blogging API is invented, someone just needs to write a driver for
the <classname>Services_Blogging</classname> package, and everyone can access
also this blogs.
</para>
<para>
As of April 2007, the package has the following drivers:
<itemizedlist>
<listitem><para>Blogger</para></listitem>
<listitem><para>LiveJournal</para></listitem>
<listitem><para>MetaWeblog</para></listitem>
</itemizedlist>
</para>
</sect2>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=webservices fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/peardoc/en/package/webservices/services-blogging/posts.xml?view=markup&rev=1.1
Index: peardoc/en/package/webservices/services-blogging/posts.xml
+++ peardoc/en/package/webservices/services-blogging/posts.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<sect2 id="package.webservices.services-blogging.posts">
<title>Blog posts / entries</title>
<para>
Beside the difference in features regarding reading and listing existing
posts, the APIs have different support for blog post properties.
While some simple APIs only allow to define the text of a post, better
ones allow to set the title and other ones also support extendet properties
like date, date to publish, categories and other.
</para>
<para>
Once you have the driver object for your blog, you should get a list of
post properties supported by your driver. The method is
<function>getSupportedPostProperties</function>; it returns an array
of property names. Currently, the following properties are possible:
</para>
<itemizedlist>
<listitem><para><literal>title</literal></para></listitem>
<listitem><para><literal>content</literal></para></listitem>
<listitem><para><literal>publishdate</literal></para></listitem>
<listitem><para><literal>date</literal></para></listitem>
<listitem><para><literal>url</literal></para></listitem>
<listitem><para><literal>categories</literal></para></listitem>
</itemizedlist>
<para>
See the API documentation of <classname>Services_Blogging_Post</classname>
for the data types.
</para>
</sect2>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=webservices fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
--
PEAR Documentation List Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic