From 7c957fc96c4ae25d8c3fa07532283f88dfb8d91b Mon Sep 17 00:00:00 2001 From: rtio Date: Thu, 24 Nov 2022 23:08:54 -0300 Subject: [PATCH] Update docs --- docs/_config.yml | 14 +- docs/conf.py | 2 +- docs/index.md | 222 +------- ...ertube-outbox-activities-using-dialects.md | 198 ------- ...tube-outbox-activities-using-ontologies.md | 91 ---- ...xample-fetch-peertube-outbox-activities.md | 339 ------------ docs/server/server-implementation.md | 95 ---- docs/server/server-usage.md | 491 ------------------ docs/server/verify-http-signatures.md | 81 --- 9 files changed, 13 insertions(+), 1520 deletions(-) delete mode 100644 docs/server/example-fetch-peertube-outbox-activities-using-dialects.md delete mode 100644 docs/server/example-fetch-peertube-outbox-activities-using-ontologies.md delete mode 100644 docs/server/example-fetch-peertube-outbox-activities.md delete mode 100644 docs/server/server-implementation.md delete mode 100644 docs/server/server-usage.md delete mode 100644 docs/server/verify-http-signatures.md diff --git a/docs/_config.yml b/docs/_config.yml index da1138b..e8bafc2 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -5,15 +5,15 @@ pygments: true enableRobotsTXT: true # Site name (head) -name: ActivityPhp Documentation +name: ActivityPhp Core Documentation # Site description (head) -description: A PHP implementation of ActivityPub protocol based upon the ActivityStreams 2.0 data format. +description: A PHP implementation of ActivityPub core types protocol based upon the ActivityStreams 2.0 data format. # Github repositories and download URLs -repository_url : https://github.com/landrok/activitypub -doc_repository_url: https://github.com/landrok/activitypub/tree/master/docs -github_author_url : https://github.com/landrok -doc_baseurl : https://landrok.github.io/activitypub -github_author_name: landrok +repository_url : https://github.com/rtio/activitypub-core +doc_repository_url: https://github.com/rtio/activitypub-core/tree/master/docs +github_author_url : https://github.com/rtio +doc_baseurl : https://rtio.github.io/activitypub-core +github_author_name: rtio diff --git a/docs/conf.py b/docs/conf.py index 98e2ff3..1eb45f8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,7 +15,7 @@ source_suffix = '.rst' master_doc = 'index' project = u'ActivityPhp' -copyright = u'Landrok' +copyright = u'rtio' version = '1' html_title = "ActivityPhp Documentation" html_short_title = "ActivityPhp" diff --git a/docs/index.md b/docs/index.md index a29ca6b..02b2f0c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -43,17 +43,6 @@ Basics - [Use your own extended types]({{ site.doc_baseurl }}/#use-your-own-extended-types) - [Create your own property validator]({{ site.doc_baseurl }}/#create-your-own-property-validator) - [Dialects management]({{ site.doc_baseurl }}/activitypub-dialects-management.html) -- [Server](#server) - - [Server instance configuration]({{ site.doc_baseurl }}/activitypub-server-usage.html) - - [Verify HTTP signatures]({{ site.doc_baseurl }}/activitypub-server-verify-http-signatures.html) - - [WebFinger]({{ site.doc_baseurl }}/#webfinger) - - [WebFinger::toArray()]({{ site.doc_baseurl }}/#webfingertoarray) - - [WebFinger::getSubject()]({{ site.doc_baseurl }}/#webfingergetsubject) - - [WebFinger::getProfileId()]({{ site.doc_baseurl }}/#webfingergetprofileid) - - [WebFinger::getHandle()]({{ site.doc_baseurl }}/#webfingergethandle) - - [WebFinger::getAliases()]({{ site.doc_baseurl }}/#webfingergetaliases) - - [WebFinger::getLinks()]({{ site.doc_baseurl }}/#webfingergetlinks) - - [Examples]({{ site.doc_baseurl }}/#server-examples) ________________________________________________________________________ @@ -68,7 +57,7 @@ Install ------- ```sh -composer require landrok/activitypub +composer require rtio/activitypub-core ``` ________________________________________________________________________ @@ -77,7 +66,7 @@ Types ### Type factory -You can instanciate ActivityStreams types using their short name. +You can instantiate ActivityStreams types using their short name. ```php use ActivityPhp\Type; @@ -87,7 +76,7 @@ $note = Type::create('Note'); ``` -Instanciating a type and setting properties is possible with the second +Instantiate a type and setting properties is possible with the second parameter. ```php @@ -100,7 +89,7 @@ $note = Type::create('Note', [ ``` Starting from an array with a 'type' key, it's even possible to directly -instanciate your type. +instantiate your type. ```php use ActivityPhp\Type; @@ -519,209 +508,10 @@ and how to use them thanks to ________________________________________________________________________ - -Server ------- - -A server instance is the entry point to a federation. - -Its purpose is to receive, send and forward activities appropriately. - -A minimalistic approach is: - -```php -use ActivityPhp\Server; - -$server = new Server(); -``` - -It's sufficient to make [some public requests](#server-examples). - -For more advanced server configurations, Have a look at [Server Manual]({{ site.doc_baseurl }}/activitypub-server-usage.html). - -### WebFinger - -WebFinger is a protocol that allows for discovery of information about -people. - -Given a handle, ActivityPub instances can discover profiles using this -protocol. - -```php -use ActivityPhp\Server; - -$server = new Server(); - -$handle = 'bob@example.org'; - -// Get a WebFinger instance -$webfinger = $server->actor($handle)->webfinger(); -``` - -In this implementation, we can use an Object Identifier (URI) instead of -a WebFinger handle. - - -```php -use ActivityPhp\Server; - -$server = new Server(); - -$handle = 'https://example.org/users/bob'; - -// Get a WebFinger instance -$webfinger = $server->actor($handle)->webfinger(); -``` -________________________________________________________________________ - -### WebFinger::toArray() - -Get all WebFinger data as an array. - -```php -use ActivityPhp\Server; - -$server = new Server(); - -$handle = 'bob@example.org'; - -// Get a WebFinger instance -$webfinger = $server->actor($handle)->webfinger(); - -// Dumps all properties -print_r($webfinger->toArray()); - -// A one line call -print_r( - $server->actor($handle)->webfinger()->toArray() -); -``` - -Would output something like: - -``` -Array -( - [subject] => acct:bob@example.org - [aliases] => Array - ( - [0] => http://example.org/users/bob - ) - [links] => Array - ( - [0] => Array - ( - [rel] => self - [type] => application/activity+json - [href] => http://example.org/users/bob - ) - ) -) -``` -________________________________________________________________________ - -### WebFinger::getSubject() - -Get a WebFinger resource. - -```php -echo $webfinger->getSubject(); - -// Would output 'acct:bob@example.org' -``` -________________________________________________________________________ - -### WebFinger::getProfileId() - -Get ActivityPub object identifier (URI). - -```php -echo $webfinger->getProfileId(); - -// Would output 'http://example.org/users/bob' -``` -________________________________________________________________________ - -### WebFinger::getHandle() - -Get a profile handle. - -```php -echo $webfinger->getHandle(); - -// Would output 'bob@example.org' -``` -________________________________________________________________________ - -### WebFinger::getAliases() - -Get all aliases entries for this profile. - -```php -print_r( - $webfinger->getAliases() -); -``` - -Would output something like: - -``` -Array -( - [0] => http://example.org/users/bob -) -``` - -________________________________________________________________________ - -### WebFinger::getLinks() - -Get all links entries for this profile. - -```php - -print_r( - $webfinger->getLinks() -); - -``` - -Would output something like: - -``` -Array -( - [0] => Array - ( - [rel] => self - [type] => application/activity+json - [href] => http://example.org/users/bob - ) -) - -``` - -________________________________________________________________________ - - -Server examples ---------------- - -- [Fetch Peertube Outbox activities]({{ site.doc_baseurl }}/fetch-peertube-outbox-activities.html) -- [A better way to fetch Peertube Outbox activities]({{ site.doc_baseurl }}/fetch-peertube-outbox-activities-using-dialects.html) -- [An even better way to fetch Peertube Outbox activities]({{ site.doc_baseurl }}/fetch-peertube-outbox-activities-using-ontologies.html) - -________________________________________________________________________ - - More ---- -- [Contribute on Github](https://github.com/landrok/activitypub) - -- To discuss new features, make feedback or simply to share ideas, you - can contact me on Mastodon at - [https://cybre.space/@landrok](https://cybre.space/@landrok) +- [Contribute on Github](https://github.com/rtio/activitypub-core) - [ActivityPub](https://www.w3.org/TR/activitypub/) @@ -729,8 +519,6 @@ More - [JSON-LD](https://www.w3.org/TR/json-ld/) -- [WebFinger](https://tools.ietf.org/html/rfc7033) - ________________________________________________________________________ diff --git a/docs/server/example-fetch-peertube-outbox-activities-using-dialects.md b/docs/server/example-fetch-peertube-outbox-activities-using-dialects.md deleted file mode 100644 index b588580..0000000 --- a/docs/server/example-fetch-peertube-outbox-activities-using-dialects.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -layout: default -permalink: fetch-peertube-outbox-activities-using-dialects.html -title: Fetch Peertube Outbox activities using ActivityPhp's dialects in PHP -excerpt: How to fetch Peertube Outbox activities using ActivityPhp's dialects in PHP. ---- - -Using dialects to fetch Peertube Outbox activities -================================================== - -For some usages, you may use an instance without having to configure -many items. - -For instance, if you want to fetch some public activities, you don't -need to have a fully-configured server instance. Indeed, you don't need -any configuration at all. - - -Fetch an Outbox ---------------- - -```php -use ActivityPhp\Server; - -// Create a server instance -$server = new Server(); - -$handle = 'nickname@example.org'; - -// Get an actor's outbox as an OrderedCollection -$outbox = $server->outbox($handle); - -// Prepare a stack -$pages = []; - -// Browse first page -$page = $outbox->getPage($outbox->get()->first); - -// Browse all pages and get public actvities -$pages[] = $page; -while ($page->next !== null) { - $page = $outbox->getPage($page->next); - $pages[] = $page; -} - -``` - -And that's it, you have an array containing all pages. - -Therefore, if you test this implementation on a real world -ActivityPub-powered application like Peertube, you would have something -like: - -```sh -Exception: Property "uuid" is not defined. Type="Video", Class="\ActivityPhp\Type\Extended\Object\Video" -``` - -Indeed, Peertube (and others like Mastodon) extends the ActivityPub -object model to fit their needs. - -So, in order to fetch Peertube's activities, we need to extend our base -models with Peertube dialect. - -________________________________________________________________________ - - -Define Peertube's dialect -------------------------- - -We will only *partially* implement peertube's model. - -After a step-by-step exceptions analysis, we've collected all attributes -that are specific. - - -```php -use ActivityPhp\Server; - -/* ------------------------------------------------------------------ - | We'll use the following definitions to fit PeerTube's dialect - ------------------------------------------------------------------ */ - -$peertube = [ - 'Group' => ['support'], - 'Video' => [ - 'uuid', 'category', 'language', 'views', 'sensitive', 'waitTranscoding', - 'state', 'commentsEnabled', 'support', 'subtitleLanguage', 'likes', - 'dislikes', 'shares', 'comments', 'licence' - ], - 'Image' => ['width', 'height'], - 'Link' => ['fps', 'mimeType', 'size' ], - 'Hashtag' => ['type'], - 'Person|Group' => ['uuid', 'publicKey'], -]; - -``` - -After that, we set these definitions as peertube's dialect: - -```php -// Create a server instance with a custom dialect -$server = new Server([ - 'dialects' => [ - 'peertube' => $peertube, - ] -]); -``` - -And now we can work with Peertube's objects! - -________________________________________________________________________ - - -Fetch Peertube Outbox activities --------------------------------- - -Below, a complete script to work with Peertube's objects. It browses all -outbox pages, collect all activities and display a list of activities -and their videos names. - -```php -use ActivityPhp\Server; - -/* ------------------------------------------------------------------ - | We'll use the following definitions to fit PeerTube's dialect - ------------------------------------------------------------------ */ -$peertube = [ - 'Group' => ['support'], - 'Video' => [ - 'uuid', 'category', 'language', 'views', 'sensitive', 'waitTranscoding', - 'state', 'commentsEnabled', 'support', 'subtitleLanguage', 'likes', - 'dislikes', 'shares', 'comments', 'licence' - ], - 'Image' => ['width', 'height'], - 'Link' => ['fps', 'mimeType', 'size' ], - 'Hashtag' => ['type'], - 'Person|Group' => ['uuid', 'publicKey'], -]; - - -/* ------------------------------------------------------------------ - | Now we can use an instance with a PeerTube flavor - ------------------------------------------------------------------ */ - -// Create a server instance with a custom dialect -$server = new Server([ - 'dialects' => [ - 'peertube' => $peertube, - ] -]); - -$handle = 'nickname@example.org'; - -// Get an actor's outbox as an OrderedCollection -$outbox = $server->outbox($handle); - -// Prepare a stack -$pages = []; - -// Browse first page -$page = $outbox->getPage($outbox->get()->first); - -// Browse all pages and get public actvities -$pages[] = $page; -while ($page->next !== null) { - $page = $outbox->getPage($page->next); - $pages[] = $page; -} - -// Now we can work with pages -foreach ($pages as $page) { - foreach ($page->orderedItems as $item) { - echo sprintf( - "Type=%s, Name=%s\n", - $item->type, // Activity type - $item->object->name // Video name - ); - } -} -``` - -________________________________________________________________________ - -Read more ---------- - -- [Extending ActivityPub Vocabulary with custom dialects]({{ site.doc_baseurl }}/activitypub-dialects-management.html). - -- [Configuring a server instance]({{ site.doc_baseurl }}/activitypub-server-usage.html). - -- [Server methods]({{ site.doc_baseurl }}/#server). - - -________________________________________________________________________ - - -{% capture doc_url %}{{ site.doc_repository_url }}/server/example-fetch-peertube-outbox-activities-using-dialects.md{% endcapture %} -{% include edit-doc-link.html %} diff --git a/docs/server/example-fetch-peertube-outbox-activities-using-ontologies.md b/docs/server/example-fetch-peertube-outbox-activities-using-ontologies.md deleted file mode 100644 index 4ba99bd..0000000 --- a/docs/server/example-fetch-peertube-outbox-activities-using-ontologies.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -layout: default -permalink: fetch-peertube-outbox-activities-using-ontologies.html -title: Fetch Peertube Outbox activities using ActivityPhp's ontologies in PHP -excerpt: How to fetch Peertube Outbox activities using ActivityPhp's ontologies in PHP. ---- - -Using ontologies to fetch Peertube Outbox activities -==================================================== - -There are 2 ways to use ontologies: - -- use existing ontologies -- define a new one and load it - -Luckily, ActivityPhp is packaged with Peertube's ontology. - -So, you just have to set `peertube` configuration. - -If you want to be more permissive (in order to work with all federated -ontologies), simply use `*` parameter. - - -Fetch Peertube Outbox activities --------------------------------- - -Below, a complete script to work with Peertube's objects. It browses all -outbox pages, collect all activities and display a list of activities -and their videos names. - -```php -use ActivityPhp\Server; - -/* ------------------------------------------------------------------ - | Use an instance with a PeerTube flavor - ------------------------------------------------------------------ */ - -// Create a server instance and allow peertube ontology -$server = new Server([ - 'ontologies' => [ - 'peertube', - ] -]); - -$handle = 'nickname@example.org'; - -// Get an actor's outbox as an OrderedCollection -$outbox = $server->outbox($handle); - -// Prepare a stack -$pages = []; - -// Browse first page -$page = $outbox->getPage($outbox->get()->first); - -// Browse all pages and get public actvities -$pages[] = $page; -while ($page->next !== null) { - $page = $outbox->getPage($page->next); - $pages[] = $page; -} - -// Now we can work with pages -foreach ($pages as $page) { - foreach ($page->orderedItems as $item) { - echo sprintf( - "Type=%s, Name=%s\n", - $item->type, // Activity type - $item->object->name // Video name - ); - } -} -``` - -________________________________________________________________________ - -Read more ---------- - -- [Extending ActivityPub Vocabulary with custom ontologies]({{ site.doc_baseurl }}/activitypub-ontologies-management.html). - -- [Configuring a server instance]({{ site.doc_baseurl }}/activitypub-server-usage.html). - -- [Server methods]({{ site.doc_baseurl }}/#server). - - -________________________________________________________________________ - - -{% capture doc_url %}{{ site.doc_repository_url }}/server/example-fetch-peertube-outbox-activities-using-ontologies.md{% endcapture %} -{% include edit-doc-link.html %} diff --git a/docs/server/example-fetch-peertube-outbox-activities.md b/docs/server/example-fetch-peertube-outbox-activities.md deleted file mode 100644 index b2027ee..0000000 --- a/docs/server/example-fetch-peertube-outbox-activities.md +++ /dev/null @@ -1,339 +0,0 @@ ---- -layout: default -permalink: fetch-peertube-outbox-activities.html -title: Fetch Peertube Outbox activities in PHP -excerpt: How to fetch Peertube Outbox activities in PHP. ---- - -Fetch Peertube Outbox activities -================================ - -For some usages, you may use an instance without having to configure -many items. - -For instance, if you want to fetch some public activities, you don't -need to have a fully-configured server instance. Indeed, you don't need -any configuration at all. - - -Fetch an Outbox ---------------- - -```php -use ActivityPhp\Server; - -// Create a server instance -$server = new Server(); - -$handle = 'nickname@example.org'; - -// Get an actor's outbox as an OrderedCollection -$outbox = $server->outbox($handle); - -// Prepare a stack -$pages = []; - -// Browse first page -$page = $outbox->getPage($outbox->get()->first); - -// Browse all pages and get public actvities -$pages[] = $page; -while ($page->next !== null) { - $page = $outbox->getPage($page->next); - $pages[] = $page; -} - -``` - -And that's it, you have an array containing all pages. - -Therefore, if you test this implementation on a real world -ActivityPub-powered application like Peertube, you would have something -like: - -```sh -Exception: Property "uuid" is not defined. Type="Video", Class="\ActivityPhp\Type\Extended\Object\Video" -``` - -Indeed, Peertube (and others like Mastodon) extends the ActivityPub -object model to fit their needs. - -So, in order to fetch Peertube's activities, we need to extend our base -models with Peertube dialect. - -________________________________________________________________________ - - -Define Peertube's dialect -------------------------- - -We will only *partially* implement peertube's model. - -After a step-by-step exceptions analysis, we've collected all attributes -that are specific. - - -```php -use ActivityPhp\Type; -use ActivityPhp\Type\Core\ObjectType; -use ActivityPhp\Type\Core\Link as BaseLink; -use ActivityPhp\Type\Extended\Actor\Person as BasePerson; -use ActivityPhp\Type\Extended\Object\Image as BaseImage; -use ActivityPhp\Type\Extended\Object\Video as BaseVideo; - -// User -class Person extends BasePerson -{ - protected $uuid; // Peertube specific - protected $publicKey; // Peertube specific -} - -// Channel -class Group extends Person -{ - protected $support; // Peertube specific -} - -class Video extends BaseVideo -{ - protected $uuid; // Peertube specific - protected $category; // Peertube specific - protected $language; // Peertube specific - protected $views; // Peertube specific - protected $sensitive; // Peertube specific - protected $waitTranscoding; // Peertube specific - protected $state; // Peertube specific - protected $commentsEnabled; // Peertube specific - protected $support; // Peertube specific - protected $subtitleLanguage;// Peertube specific - protected $likes; // Peertube specific - protected $dislikes; // Peertube specific - protected $shares; // Peertube specific - protected $comments; // Peertube specific - protected $licence; // Peertube specific -} - -class Image extends BaseImage -{ - protected $width; // Peertube specific - protected $height; // Peertube specific -} - -class Link extends BaseLink -{ - protected $fps; // Peertube specific - protected $mimeType; // Peertube specific - protected $size; // Peertube specific -} - -// Create a new Type -class HashTag extends ObjectType -{ - protected $type = 'HashTag';// Peertube specific -} -``` - -If you need to implement a specific dialect, just have a look at our -[ActivityStreams types]({{ site.doc_baseurl }}/activitystreams-types.html). -Then, you may see which properties are already defined: - -```php -use ActivityPhp\Type; - -print_r( - Type::create('Video')->getProperties() -); -``` - -This will output all normalized ActivityPub's properties for a type. - -```sh -Array -( - [0] => type - [1] => id - [2] => attachment - [3] => attributedTo - [4] => audience - [5] => content - [6] => context - [7] => contentMap - [8] => name - [9] => nameMap - [10] => endTime - [11] => generator - [12] => icon - [13] => image - [14] => inReplyTo - [15] => location - [16] => preview - [17] => published - [18] => replies - [19] => startTime - [20] => summary - [21] => summaryMap - [22] => tag - [23] => updated - [24] => url - [25] => to - [26] => bto - [27] => cc - [28] => bcc - [29] => mediaType - [30] => duration - [31] => source -) - -``` - -After that, we push all new definitions into our pool: - -```php -// Add custom definitions to override defaults or introduce new ones -Type::add('Group', Group::class); -Type::add('HashTag', HashTag::class); # new one -Type::add('Image', Image::class); -Type::add('Link', Link::class); -Type::add('Person', Person::class); -Type::add('Video', Video::class); -``` - -And now we can work with Peertube's objects! - -________________________________________________________________________ - - -Fetch Peertube Outbox activities --------------------------------- - -Below, a complete script to work with Peertube's objects. It browses all -outbox pages, collect all activities and display a list of activities -and their videos names. - -```php -use ActivityPhp\Type; -use ActivityPhp\Server; - -/* ------------------------------------------------------------------ - | We'll use the following definitions to fit PeerTube's dialect - ------------------------------------------------------------------ */ -use ActivityPhp\Type\Core\ObjectType; -use ActivityPhp\Type\Core\Link as BaseLink; -use ActivityPhp\Type\Extended\Actor\Person as BasePerson; -use ActivityPhp\Type\Extended\Object\Image as BaseImage; -use ActivityPhp\Type\Extended\Object\Video as BaseVideo; - -// User -class Person extends BasePerson -{ - protected $uuid; // Peertube specific - protected $publicKey; // Peertube specific -} - -// Channel -class Group extends Person -{ - protected $support; // Peertube specific -} - -class Video extends BaseVideo -{ - protected $uuid; // Peertube specific - protected $category; // Peertube specific - protected $language; // Peertube specific - protected $views; // Peertube specific - protected $sensitive; // Peertube specific - protected $waitTranscoding; // Peertube specific - protected $state; // Peertube specific - protected $commentsEnabled; // Peertube specific - protected $support; // Peertube specific - protected $subtitleLanguage;// Peertube specific - protected $likes; // Peertube specific - protected $dislikes; // Peertube specific - protected $shares; // Peertube specific - protected $comments; // Peertube specific - protected $licence; // Peertube specific -} - -class Image extends BaseImage -{ - protected $width; // Peertube specific - protected $height; // Peertube specific -} - -class Link extends BaseLink -{ - protected $fps; // Peertube specific - protected $mimeType; // Peertube specific - protected $size; // Peertube specific -} - -// Create a new Type -class HashTag extends ObjectType -{ - protected $type = 'HashTag';// Peertube specific -} - -// Add custom definitions to override defaults or introduce new ones -Type::add('Group', Group::class); -Type::add('HashTag', HashTag::class); # new one -Type::add('Image', Image::class); -Type::add('Link', Link::class); -Type::add('Person', Person::class); -Type::add('Video', Video::class); - - -/* ------------------------------------------------------------------ - | Now we can use an instance with a PeerTube flavor - ------------------------------------------------------------------ */ - -// Create a server instance -$server = new Server(); - -$handle = 'nickname@example.org'; - -// Get an actor's outbox as an OrderedCollection -$outbox = $server->outbox($handle); - -// Prepare a stack -$pages = []; - -// Browse first page -$page = $outbox->getPage($outbox->get()->first); - -// Browse all pages and get public actvities -$pages[] = $page; -while ($page->next !== null) { - $page = $outbox->getPage($page->next); - $pages[] = $page; -} - -// Now we can work with pages -foreach ($pages as $page) { - foreach ($page->orderedItems as $item) { - echo sprintf( - "Type=%s, Name=%s\n", - $item->type, // Activity type - $item->object->name // Video name - ); - } -} -``` - -________________________________________________________________________ - -Read more ---------- - -- [Fetching Peertube outbox activities using dialects]({{ site.doc_baseurl }}/fetch-peertube-outbox-activities-using-dialects.html). - -- [Configuring a server instance]({{ site.doc_baseurl }}/activitypub-server-usage.html). - -- [How a server instance is working]({{ site.doc_baseurl }}/#server). - - -________________________________________________________________________ - - -{% capture doc_url %}{{ site.doc_repository_url }}/server/example-fetch-peertube-outbox-activities.md{% endcapture %} -{% include edit-doc-link.html %} diff --git a/docs/server/server-implementation.md b/docs/server/server-implementation.md deleted file mode 100644 index ba7758d..0000000 --- a/docs/server/server-implementation.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -layout: default -permalink: activitypub-server-implementation.html -title: ActivityPub server implementation in PHP -excerpt: How to implement an ActivityPub server in PHP. ---- - -Implement an ActivityPub server -=============================== - -Usage ------ - -```php -use ActivityPhp\Server; - -// Create a server instance -$server = new Server(); - -// Post an activity -$response = $server->outbox("actor@example.com")->post([ - "@context" => "https://www.w3.org/ns/activitystreams", - "type" => "Note", - "content" => "This is a note", - "published" => "2015-02-10T15:04:55Z", - "to" => ["https =>//example.org/~john/"], - "cc" => [ - "https =>//example.com/~erik/followers", - "https =>//www.w3.org/ns/activitystreams#Public" - ] -]); - -``` - -`$response` is a `ActivityPub\Server\Response` class; - - -Response methods ----------------- - -getStatus - -getCode - -getLocation - -hasError - - -Server parameters ------------------ - -A server instance can receive a configuration array as first parameter. - -```php -use ActivityPhp\Server; - -// Create a server instance -$server = new Server([ - 'logger' => [], - 'instance' => [], - 'http' => [], - 'database' => [], - 'cache' => [], - 'jobs' => [] -]); -``` - -________________________________________________________________________ - -### logger parameters - -- channel: A string defining a log channel. Default is 'global' - -- loglevel: Minimal loglevel. Default is Logger::DEBUG (@todo put all monolog - allowed config) - -- stream: Where to put log messages. Default is 'php://stdout'. - It can be a filename. - -________________________________________________________________________ - - -### instance parameters - -- hostname -- debug: boolean. - default = false - - -________________________________________________________________________ - - -{% capture doc_url %}{{ site.doc_repository_url }}/activitystreams-types.md{% endcapture %} -{% include edit-doc-link.html %} diff --git a/docs/server/server-usage.md b/docs/server/server-usage.md deleted file mode 100644 index bb3b081..0000000 --- a/docs/server/server-usage.md +++ /dev/null @@ -1,491 +0,0 @@ ---- -layout: default -permalink: activitypub-server-usage.html -title: ActivityPub server usage in PHP -excerpt: How to use an ActivityPub server in PHP. ---- - -ActivityPub Server - Usage -========================== - -*Server features are still a WIP.* - -Usage ------ - -```php -use ActivityPhp\Server; - -// Create a server instance -$server = new Server(); - -``` - -It's a very minimalistic example of use. With this configuration, an -instance can only request for public activities and can't receive some -data. - -As you could imagine, a server instance, to be fully-functional, must -accept some parameters. - -Server parameters ------------------ - -A server instance can receive an array of configurations as first -parameter. - -```php -use ActivityPhp\Server; - -// Create a server instance with parameters -$server = new Server([ - 'logger' => [], - 'instance' => [], - 'cache' => [], - 'http' => [], - 'dialects' => [], - 'ontologies' => [], -]); -``` - -Each array defines a scope of configuration. - -________________________________________________________________________ - -### Logger parameters - -Sometimes, for testing purpose, it may be suitable to block log output. - -**driver** - -```php -use ActivityPhp\Server; - -// Create a server instance with no log output -$server = new Server([ - 'logger' => [ - 'driver' => '\Psr\Log\NullLogger' - ], -]); -``` - -If you have specific needs (Storing logs into a database, for -instance), you may pass a custom logger driver. As it implements -`Psr\Log\LoggerInterface`, you may pass any custom logger. - -By default, the driver is [Monolog\Logger](https://github.com/Seldaek/monolog). - - -**stream** - -The default output for logging message is `php://stdout`. -You can pass a filename where logs will be put. - -```php -use ActivityPhp\Server; - -// Put logs into a specific file -$server = new Server([ - 'logger' => [ - 'stream' => '/var/log/activitypub/server.log' - ], -]); -``` - - -**channel** - -The default channel is `global`. in order to customize, you can pass a -channel parameter. - -```php -use ActivityPhp\Server; - -// Put logs with a specific channel -$server = new Server([ - 'logger' => [ - 'channel' => 'ap_channel' - ], -]); -``` - -________________________________________________________________________ - - -### Instance parameters - - -**host** - -The default hostname is `localhost`. If you want to be reachable from -a network you may pass a custom hostname. - -```php -use ActivityPhp\Server; - -$server = new Server([ - 'instance' => [ - 'host' => 'activitypub.example.org' - ], -]); -``` - -**port** - -The default port is `443`. If you want to customize it, you may pass a -port parameter. - -```php -use ActivityPhp\Server; - -$server = new Server([ - 'instance' => [ - 'port' => 8000 - ], -]); -``` - -Note: this does not seem to be supported by all ActivityPub servers of -the federation. - -**types** - -This option tells the instance which behaviour when an unknown property -or an undefined type is encountered. - -All federations (mastodon, peertube, pixelfed, etc...) are implementing -non standard activity streams properties and types. - -By default, an instance is configured in `strict` mode. When a non- -standard type is encountered, if it's not defined as a dialect, it -throws an exception. - -It can be blocking if you're working with many kinds of federations. - -So, you may configure your instance with a less strict requirement in two -ways: - -- `ignore` : non standard types and properties are ignored -- `include`: non standard types and properties are set and created on -the fly. - - -```php -use ActivityPhp\Server; - -$server = new Server([ - 'instance' => [ - 'types' => 'include' - ], -]); -``` - - -**debug** - -For testing purpose, you may use HTTP scheme instead of HTTPS. -The debug parameter is made for that. - -```php -use ActivityPhp\Server; - -$server = new Server([ - 'instance' => [ - 'debug' => true - ], -]); -``` - -For security purpose, the default value is `false`. - -________________________________________________________________________ - - -### HTTP parameters - - -**timeout** - -The default timeout for HTTP requests is `10s`.. - -```php -use ActivityPhp\Server; - -// Increase HTTP request timeout to 20 seconds -$server = new Server([ - 'http' => [ - 'timeout' => '20' - ], -]); -``` - -**agent** - -When talking to other federated servers, an instance -uses the default user agent *ActivityPhp/x.y.z (+https://{host})*. - -It can be customized with agent parameter. - -```php -use ActivityPhp\Server; - -$server = new Server([ - 'http' => [ - 'agent' => 'MyCustomUserAgent' - ], -]); -``` - -________________________________________________________________________ - - -### Cache parameters - - -**type** - -The default type of cache is `filesystem`. Cache is actived by default. - - -**enabled** - -You can disable caching objects with `enabled` parameter. - -```php -use ActivityPhp\Server; - -$server = new Server([ - 'cache' => [ - 'enabled' => false - ], -]); -``` - -**stream** - -By default, it stores cache files in the common working directory (See -[PHP getcwd() manual](http://php.net/manual/en/function.getcwd.php)). - -You can customize where cache files are stored with the `stream` -parameter. - - -```php -use ActivityPhp\Server; - -$server = new Server([ - 'cache' => [ - 'stream' => '/mycustom/directory' - ], -]); -``` - -**ttl** - -The Time To Live (TTL) of an item is the amount of time in seconds -between when that item is stored and it is considered stale. - -The default value is 3600. - -```php -use ActivityPhp\Server; - -$server = new Server([ - 'cache' => [ - 'ttl' => 60 // Set to 60 seconds - ], -]); -``` - -**pool** - -ActivtyPhp comes with a default cache driver `\Symfony\Component\Cache\Adapter\FilesystemAdapter`. - -There are 2 ways to override this driver with __pool__ parameter. - -You can pass a class name that will be automatically instanciated. - -```php -use ActivityPhp\Server; - -$server = new Server([ - 'cache' => [ - 'pool' => 'Symfony\Component\Cache\Adapter\ArrayAdapter' - ], -]); -``` - -If you need a cache pool with custom configuration, you can pass an -instanciated pool. - -```php -use ActivityPhp\Server; -use Symfony\Component\Cache\Adapter\ArrayAdapter; - -$server = new Server([ - 'cache' => [ - 'pool' => new ArrayAdapter() - ], -]); -``` - -The given pool must implement `Psr\Cache\CacheItemPoolInterface`. - -__Note__ - -All [Symfony cache adapters](https://symfony.com/doc/current/components/cache.html#available-cache-adapters) -are supplied as dependencies. - -________________________________________________________________________ - - -### Dialects parameters - -Dialect parameter has a special role. - -It defines and load ActivityPub types and properties which are not -defined in the standard protocol. - - -**type** - -This parameter is a 3-levels array containing: - -`DialectName => Types => Properties` - -**example** - -In this example, we define 2 dialects with 1 type for each. - -The first type extends ActivityPub `Person` type with an `uuid` property. -The second type creates a new type `HashTag` with 2 properties, `uuid` -and `name`. - -```php -use ActivityPhp\Server; - -$dialect1 = [ - 'Person' => ['uuid'], -]; - -$dialect2 = [ - 'HashTag' => ['uuid', 'name'], -]; - -$server = new Server([ - 'dialects' => [ - 'dialect1' => $dialect1, - 'dialect2' => $dialect2, - ], -]); -``` - -After this loading, the new types and properties are usable. - - -```php -use ActivityPhp\Type; - -$hashtag = Type::create([ - 'type' => 'HashTag', - 'uuid' => 42, - 'name' => 'myTag' -]; - -$person = Type::create([ - 'type' => 'Person', - 'uuid' => 42 -]; -``` - -[More about dialects management]({{ site.doc_baseurl }}/activitypub-dialects-management.html) - -[An example of Peertube's dialect implementation]({{ site.doc_baseurl }}/fetch-peertube-outbox-activities-using-dialects.html) - -________________________________________________________________________ - -________________________________________________________________________ - - -### Ontologies parameters - -Ontology parameter has a special role. - -It defines and load ActivityPub types and properties which are not -defined in the standard protocol but that are commonly used by Federated -applications. It permits that your application will be compatible with -other federations. - -**type** - -This parameter is a 1 or 2-levels array containing: - -`OntologyName` - -or - -`OntologyName` => `CustomOntologyClassName` - -**examples** - -In this example, we load Peertube's ontology. - -It's a packaged ontology. - -```php -$server = new Server([ - 'ontologies' => [ - 'peertube' - ], -]); -``` - -After this loading, the new types and properties are usable. - -In this second example, we load all predefined (packaged) ontologies. - -```php -$server = new Server([ - 'ontologies' => [ - '*' - ], -]); -``` - -You can create and define your custom ones and load them. - -```php -$server = new Server([ - 'ontologies' => [ - 'my-ontology' => MyClass::class - ], -]); -``` - -For more informations about creating your custom ontology, see the -dedicated manual -[ontologies management manual]({{ site.doc_baseurl }}/activitypub-ontologies-management.html) - - -Obviously, you can load several ontologies. - -```php -$server = new Server([ - 'ontologies' => [ - 'peertube', - 'my-ontology' => MyClass::class - ], -]); -``` - -This feature needs you. Contributions are very welcome. - -[More about ontologies management]({{ site.doc_baseurl }}/activitypub-ontologies-management.html) - -[An example of Peertube's ontology implementation]({{ site.doc_baseurl }}/fetch-peertube-outbox-activities-using-dialects.html) - -________________________________________________________________________ - - -{% capture doc_url %}{{ site.doc_repository_url }}/server/server-usage.md{% endcapture %} -{% include edit-doc-link.html %} diff --git a/docs/server/verify-http-signatures.md b/docs/server/verify-http-signatures.md deleted file mode 100644 index 98fe040..0000000 --- a/docs/server/verify-http-signatures.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -layout: default -permalink: activitypub-server-verify-http-signatures.html -title: Verify an HTTP signature with ActivityPub server in PHP -excerpt: How to verify an HTTP signature with ActivityPub server in PHP. ---- - -ActivityPub Server - Verifying HTTP signatures -============================================== - -ActivityPhp server automatically verifies HTTP signatures when handling -a POST to an inbox (incoming messages). - -For an out-of-the-box usage, a dedicated tool is provided, it's called `HttpSignature`. - -Usage ------ - -```php -use ActivityPhp\Server; -use ActivityPhp\Server\Http\HttpSignature; - -// Create a server instance -$server = new Server(); - -// Create an HttpSignature instance -$httpSignature = new HttpSignature($server); - -var_dump( - // Verify signature - $httpSignature->verify($request) -); - -// Returns bool(true) if signature has been verified - -``` - -`HttpSignature` receives a server instance in its constructor method. -Indeed, it is useful to make some checks about actor who has sent this -incoming request. - -________________________________________________________________________ - -HttpSignature::verify() ------------------------ - -It returns a boolean. `true` if the signature has been verified, `false` -otherwise. - -This method accepts one parameter. It must be a -`Symfony\Component\HttpFoundation\Request` instance. - -This request MUST contain a Signature header that specifies [keyId, -headers, signature]. *headers* key is optional. - -Read more about -[HTTP signature components](https://tools.ietf.org/html/draft-cavage-http-signatures-10#section-2.1). - -The verification process follows the following steps: - -- Parse HTTP signature if it is in the headers -- Check that actor is really declared on the distant instance -- Get actor's public key -- Verify HTTP signature - -________________________________________________________________________ - -ActivityPub conformance ------------------------ - -As ActivityPub protocol does not specify an official mechanism for -[signature verification](https://www.w3.org/TR/activitypub/#authorization) -(algorithm, headers), this implementation tries to make use of -[good practices recommended by the Social Community Group](https://www.w3.org/wiki/SocialCG/ActivityPub/Authentication_Authorization#Signing_requests_using_HTTP_Signatures) -and to be compliant with empirical implementations (Mastodon, Peertube -at least). - -________________________________________________________________________ - -{% capture doc_url %}{{ site.doc_repository_url }}/server/verify-http-signatures.md{% endcapture %} -{% include edit-doc-link.html %}