README.markdown (3421B)
1 PHP SSH 2 ======= 3 4 [](https://travis-ci.org/Herzult/php-ssh) (master) 5 6 Provides an object-oriented wrapper for the php ssh2 extension. 7 8 Requirements 9 ------------ 10 11 You need PHP version 5.3+ with the [SSH2 extension](http://www.php.net/manual/en/book.ssh2.php). 12 13 Installation 14 ------------ 15 16 The best way to add the library to your project is using [composer](http://getcomposer.org). 17 18 $ composer require herzult/php-ssh:~1.0 19 20 Usage 21 ----- 22 23 ### Configuration of the connection 24 25 To establish an SSH connection, you must first define its configuration. 26 For that, create a Configuration instance with all the needed parameters. 27 28 ```php 29 <?php 30 31 // simple configuration to connect "my-host" 32 $configuration = new Ssh\Configuration('my-host'); 33 ``` 34 35 The available configuration classes are: 36 37 - `Configuration` 38 - `SshConfigFileConfiguration` 39 40 Both connection configuration and public/private key authentication can be obtained from a ssh config file such as `~/.ssh/config` 41 42 ```php 43 <?php 44 45 // simple configuration to connect "my-host" 46 $configuration = new Ssh\SshConfigFileConfiguration('/Users/username/.ssh/config', 'my-host'); 47 $authentication = $configuration->getAuthentication('optional_passphrase', 'optional_username'); 48 ``` 49 50 ### Create a session 51 52 The session is the central access point to the SSH functionality provided by the library. 53 54 ```php 55 <?php 56 57 // ... the configuration creation 58 59 $session = new Ssh\Session($configuration); 60 ``` 61 62 ### Authentication 63 64 The authentication classes allow you to authenticate over a SSH session. 65 When you define an authentication for a session, it will authenticate on connection. 66 67 ```php 68 <?php 69 70 $configuration = new Ssh\Configuration('myhost'); 71 $authentication = new Ssh\Authentication\Password('John', 's3cr3t'); 72 73 $session = new Session($configuration, $authentication); 74 ``` 75 76 The available authentication are: 77 78 - `None` for username based authentication 79 - `Password` for password authentication 80 - `PublicKeyFile` to authenticate using a public key 81 - `HostBasedFile` to authenticate using a public hostkey 82 - `Agent` to authenticate using an ssh-agent 83 84 ### Authentication from SshConfigFileConfiguration 85 86 If you use an ssh config file you can load your authentication and configuration from it as follows: 87 88 ```php 89 <?php 90 91 $configuration = new Ssh\SshConfigFileConfiguration('~/.ssh/config', 'my-host'); 92 93 $session = new Session($configuration, $configuration->getAuthentication()); 94 ``` 95 96 This will pick up your public and private keys from your config file Host and Identity declarations. 97 98 ### Subsystems 99 100 Once you are authenticated over a SSH session, you can use the subsystems. 101 102 #### Sftp 103 104 You can easily access the sftp subsystem of a session using the `getSftp()` method: 105 106 ```php 107 <?php 108 109 // the session creation 110 111 $sftp = $session->getSftp(); 112 ``` 113 114 See the `Ssh\Sftp` class for more details on the available methods. 115 116 #### Publickey 117 118 The session also provides the `getPublickey()` method to access the publickey subsystem: 119 120 ```php 121 <?php 122 123 // ... the session creation 124 125 $publickey = $session->getPublickey(); 126 ``` 127 128 See the `Ssh\Publickey` class for more details on the available methods. 129 130 #### Exec 131 132 The session provides the `getExec()` method to access the exec subsystem 133 134 ```php 135 <?php 136 137 // ... the session creation 138 139 $exec = $session->getExec(); 140 141 echo $exec->run('ls -lah'); 142 ``` 143 144 See the `Ssh\Exec` class for more details.