updated README

README.md

@@ -3,7 +3,8 @@ Phpactor Language Server
 
 [![Build Status](https://travis-ci.org/phpactor/language-server.svg?branch=master)](https://travis-ci.org/phpactor/language-server)
 
-This package provides a language server platform:
+This package provides a [language
+server](https://microsoft.github.io/language-server-protocol/specification) platform:
 
 - Language server platform upon which you can implement language server
   features.
@@ -12,74 +13,91 @@ This package provides a language server platform:
 - Can handle multiple sessions.
 - Can manage text document synchronization.
 
+See the [Language Server
+Specification](https://microsoft.github.io/language-server-protocol/specification)
+for a list of methods which you can implement with this package.
+
 Example
 -------
 
-Create a dumb language server which can synchronize text documents:
+Create a dumb language server which can respond to the `initialize` command
+and nothing more:
 
 ```php
 $server = LanguageServerBuilder::create()
     ->tcpServer()
-    ->enableTextDocumentHandler()
     ->build();
 
 $server->start();
 ```
 
-In order to support language server features we create Handlers, for example:
+Add TextDocument Handling
+-------------------------
+
+We provide a handler for text document synchronization:
 
 ```php
-<?php
+$server = LanguageServerBuilder::create()
+    ->addSystemHandler(new TextDocumentHandler(new Workspace()));
+    ->build();
 
-namespace Phpactor\LanguageServer\Example;
+$server->start();
+```
 
-use LanguageServerProtocol\CompletionItem;
-use LanguageServerProtocol\CompletionList;
-use LanguageServerProtocol\Position;
-use LanguageServerProtocol\TextDocumentItem;
-use Phpactor\LanguageServer\Core\Dispatcher\Handler;
-use Phpactor\LanguageServer\Core\Session\SessionManager;
+The text document handler will keep track of the files the client is managing.
+The workspace will contain these files, and can be used by other handlers.
 
-class ExampleCompletionHandler implements Handler
-{
-    private $sessionManager;
+Creating Custom Handlers
+------------------------
 
-    public function __construct(SessionManager $sessionManager)
-    {
-        $this->sessionManager = $sessionManager;
-    }
+Handlers simply declare a map of Language Server RPC metods to instance
+methods:
 
+```
+class MyCompletionHandler implements Handler
+{
     public function methods(): array
     {
         return [
-            'textDocument/completion' => 'complete'
+            'textDocument/completion' => 'completion',
         ];
     }
 
-    public function complete(TextDocumentItem $textDocument, Position $position): CompletionList
+    public function completion(): Generator
     {
-        $textDocument = $this->sessionManager->current()->workspace()->get($textDocument->uri);
-        $completionList = new CompletionList();
-
-        // ... do whatever we need to do to get the completion information
-
-        $completionList->items[] = new CompletionItem('foobar');
-        $completionList->items[] = new CompletionItem('foofoo');
+         $list = new CompletionList();
+         $list->items[] = new CompletionItem('hello');
+         $list->items[] = new CompletionItem('goodbye');
 
-        yield $completionList;
+         yield $list;
     }
 }
 ```
 
-Which can then be registered with the server, for example with the builder:
+Create Per-Session Handlers
+---------------------------
 
-```php
-$sessionManager = new SessionManager();
-$server = LanguageServerBuilder::create($sessionManager)
-    ->tcpServer()
-    ->enableTextDocumentHandler()
-    ->addHandler(new MyCompletionHandler($sessionManager))
-    ->build();
+Above we created a global text document handler, which isn't great as it means
+multiple clients share the same workspace.
+
+You can use `HandlerLoader` implementations to lazily create handlers each
+time a client connects to the server. It is passed the initialization
+parmeters supplied by the client (which includes the root path of the clients
+project):
 
-$server->start();
 ```
+class MyHandlerLoader
+{
+    public function load(InitializeParams $params): Handlers
+    {
+        $workspace = new Workspace();
+
+        return new Handlers([
+            new MyHandler($workspace)
+            new MyOtherHandler($workspace)
+        ]);
+    }
+}
+```
+
+

bin/serve.php

@@ -5,6 +5,7 @@
 use Phpactor\LanguageServer\Adapter\DTL\DTLArgumentResolver;
 use Phpactor\LanguageServer\Core\Connection\StreamConnection;
 use Phpactor\LanguageServer\Core\Connection\TcpServerConnection;
+use Phpactor\LanguageServer\Core\Session\Workspace;
 use Phpactor\LanguageServer\Extension\Core\Initialize;
 use Phpactor\LanguageServer\Core\IO\StreamIO;
 use Phpactor\LanguageServer\Core\ChunkIO\TcpIO;
@@ -13,6 +14,7 @@
 use Phpactor\LanguageServer\Core\Handlers;
 use Phpactor\LanguageServer\Core\Server;
 use Phpactor\LanguageServer\Core\Session\SessionManager;
+use Phpactor\LanguageServer\Handler\TextDocument\TextDocumentHandler;
 use Phpactor\LanguageServer\LanguageServerBuilder;
 use Psr\Log\AbstractLogger;
 
@@ -55,6 +57,7 @@ public function log($level, $message, array $context = [])
 $logger->info('i am a demonstration server and provide no functionality');
 
 $builder = LanguageServerBuilder::create($logger);
+$builder->addSystemHandler(new TextDocumentHandler(new Workspace()));
 $builder->tcpServer($options['address']);
 
 $server = $builder->build();