Skip to content

ConnectionSettings class: Immutability documentation #145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 26, 2023
Merged

ConnectionSettings class: Immutability documentation #145

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 26 additions & 23 deletions src/ConnectionSettings.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@

/**
* The settings used during connection to a broker.
*
* This class is immutable and all setters return a clone of the original class because
* connection settings must not change once passed to MqttClient.
*
* @package PhpMqtt\Client
*/
Expand Down Expand Up @@ -39,7 +42,7 @@ class ConnectionSettings
* The username used for authentication when connecting to the broker.
*
* @param string|null $username
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setUsername(?string $username): ConnectionSettings
{
Expand All @@ -62,7 +65,7 @@ public function getUsername(): ?string
* The password used for authentication when connecting to the broker.
*
* @param string|null $password
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setPassword(?string $password): ConnectionSettings
{
Expand All @@ -89,7 +92,7 @@ public function getPassword(): ?string
* Note: This setting has no effect on subscriptions, only on the publishing of messages.
*
* @param bool $useBlockingSocket
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function useBlockingSocket(bool $useBlockingSocket): ConnectionSettings
{
Expand All @@ -113,7 +116,7 @@ public function shouldUseBlockingSocket(): bool
* a socket connection with the broker. The value cannot be less than 1 second.
*
* @param int $connectTimeout
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setConnectTimeout(int $connectTimeout): ConnectionSettings
{
Expand All @@ -138,7 +141,7 @@ public function getConnectTimeout(): int
* The value cannot be less than 1 second.
*
* @param int $socketTimeout
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setSocketTimeout(int $socketTimeout): ConnectionSettings
{
Expand All @@ -162,7 +165,7 @@ public function getSocketTimeout(): int
* of pending messages without acknowledgement. The value cannot be less than 1 second.
*
* @param int $resendTimeout
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setResendTimeout(int $resendTimeout): ConnectionSettings
{
Expand All @@ -187,7 +190,7 @@ public function getResendTimeout(): int
* and may not be higher than 65535 seconds. A reasonable value is 10 seconds (the default).
*
* @param int $keepAliveInterval
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setKeepAliveInterval(int $keepAliveInterval): ConnectionSettings
{
Expand All @@ -212,7 +215,7 @@ public function getKeepAliveInterval(): int
* The setting cannot be used together with the clean session flag.
*
* @param bool $reconnectAutomatically
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setReconnectAutomatically(bool $reconnectAutomatically): ConnectionSettings
{
Expand All @@ -236,7 +239,7 @@ public function shouldReconnectAutomatically(): bool
* is only relevant if {@see setReconnectAutomatically()} is set to true.
*
* @param int $maxReconnectAttempts
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setMaxReconnectAttempts(int $maxReconnectAttempts): ConnectionSettings
{
Expand All @@ -260,7 +263,7 @@ public function getMaxReconnectAttempts(): int
* This setting is only relevant if {@see setReconnectAutomatically()} is set to true.
*
* @param int $delayBetweenReconnectAttempts
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setDelayBetweenReconnectAttempts(int $delayBetweenReconnectAttempts): ConnectionSettings
{
Expand All @@ -287,7 +290,7 @@ public function getDelayBetweenReconnectAttempts(): int
* message are configured.
*
* @param string|null $lastWillTopic
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setLastWillTopic(?string $lastWillTopic): ConnectionSettings
{
Expand All @@ -314,7 +317,7 @@ public function getLastWillTopic(): ?string
* topic are configured.
*
* @param string|null $lastWillMessage
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setLastWillMessage(?string $lastWillMessage): ConnectionSettings
{
Expand Down Expand Up @@ -348,7 +351,7 @@ public function hasLastWill(): bool
* if it gets triggered.
*
* @param int $lastWillQualityOfService
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setLastWillQualityOfService(int $lastWillQualityOfService): ConnectionSettings
{
Expand All @@ -373,7 +376,7 @@ public function getLastWillQualityOfService(): int
* a retained offline state in the last will and an online state as first message on connect.
*
* @param bool $lastWillRetain
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setRetainLastWill(bool $lastWillRetain): ConnectionSettings
{
Expand All @@ -397,7 +400,7 @@ public function shouldRetainLastWill(): bool
* connect to the broker must support TLS connections.
*
* @param bool $useTls
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setUseTls(bool $useTls): ConnectionSettings
{
Expand All @@ -420,7 +423,7 @@ public function shouldUseTls(): bool
* This flag determines if the peer certificate is verified, if TLS is used.
*
* @param bool $tlsVerifyPeer
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setTlsVerifyPeer(bool $tlsVerifyPeer): ConnectionSettings
{
Expand All @@ -443,7 +446,7 @@ public function shouldTlsVerifyPeer(): bool
* This flag determines if the peer name is verified, if TLS is used.
*
* @param bool $tlsVerifyPeerName
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setTlsVerifyPeerName(bool $tlsVerifyPeerName): ConnectionSettings
{
Expand All @@ -468,7 +471,7 @@ public function shouldTlsVerifyPeerName(): bool
* scenarios and public services.
*
* @param bool $tlsSelfSignedAllowed
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setTlsSelfSignedAllowed(bool $tlsSelfSignedAllowed): ConnectionSettings
{
Expand All @@ -492,7 +495,7 @@ public function isTlsSelfSignedAllowed(): bool
* certificate, if TLS is used.
*
* @param string|null $tlsCertificateAuthorityFile
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setTlsCertificateAuthorityFile(?string $tlsCertificateAuthorityFile): ConnectionSettings
{
Expand Down Expand Up @@ -521,7 +524,7 @@ public function getTlsCertificateAuthorityFile(): ?string
* array under the key "hash".
*
* @param string|null $tlsCertificateAuthorityPath
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setTlsCertificateAuthorityPath(?string $tlsCertificateAuthorityPath): ConnectionSettings
{
Expand Down Expand Up @@ -549,7 +552,7 @@ public function getTlsCertificateAuthorityPath(): ?string
* A passphrase can be configured using {@see ConnectionSettings::setTlsClientCertificateKeyPassphrase()}.
*
* @param string|null $tlsClientCertificateFile
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setTlsClientCertificateFile(?string $tlsClientCertificateFile): ConnectionSettings
{
Expand All @@ -575,7 +578,7 @@ public function getTlsClientCertificateFile(): ?string
* to be used as well.
*
* @param string|null $tlsClientCertificateKeyFile
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setTlsClientCertificateKeyFile(?string $tlsClientCertificateKeyFile): ConnectionSettings
{
Expand Down Expand Up @@ -604,7 +607,7 @@ public function getTlsClientCertificateKeyFile(): ?string
* Please be aware that your passphrase is not stored in secure memory when using this option.
*
* @param string|null $tlsClientCertificateKeyPassphrase
* @return ConnectionSettings
* @return ConnectionSettings A copy of the original object with the new setting applied.
*/
public function setTlsClientCertificateKeyPassphrase(?string $tlsClientCertificateKeyPassphrase): ConnectionSettings
{
Expand Down