Skip to content

Commit 3f4705e

Browse files
GhaziTrikiGhaziTriki
committed
Imporve repository README.md
1 parent d491575 commit 3f4705e

1 file changed

Lines changed: 89 additions & 74 deletions

File tree

‎README.md‎

Lines changed: 89 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,116 +1,131 @@
11
# BigBlueButton API for PHP
22

3-
![Home Image](https://raw.githubusercontent.com/wiki/bigbluebutton/bigbluebutton-api-php/images/header.png)
4-
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fbigbluebutton%2Fbigbluebutton-api-php.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fbigbluebutton%2Fbigbluebutton-api-php?ref=badge_shield)
5-
6-
The official and easy to use **BigBlueButton API for PHP**, makes easy for developers to use [BigBlueButton][bbb] API for **PHP 8.1+**.
3+
![Header Image](https://raw.githubusercontent.com/wiki/bigbluebutton/bigbluebutton-api-php/images/header.png)
74

8-
![Packagist](https://img.shields.io/packagist/v/bigbluebutton/bigbluebutton-api-php.svg?label=release)
9-
[![Downloads](https://img.shields.io/packagist/dt/bigbluebutton/bigbluebutton-api-php.svg?style=flat-square)](https://packagist.org/packages/bigbluebutton/bigbluebutton-api-php)
5+
[![Latest Release](https://img.shields.io/packagist/v/bigbluebutton/bigbluebutton-api-php?label=Release&logo=packagist)](https://packagist.org/packages/bigbluebutton/bigbluebutton-api-php)
6+
[![Downloads](https://img.shields.io/packagist/dt/bigbluebutton/bigbluebutton-api-php?label=Downloads)](https://packagist.org/packages/bigbluebutton/bigbluebutton-api-php)
7+
[![PHP Version](https://img.shields.io/badge/PHP-8.1%2B-blue?logo=php)](https://www.php.net/supported-versions.php)
8+
[![License](https://img.shields.io/github/license/bigbluebutton/bigbluebutton-api-php?color=brightgreen)](LICENSE)
9+
[![Last Commit](https://img.shields.io/github/last-commit/bigbluebutton/bigbluebutton-api-php)](https://github.com/bigbluebutton/bigbluebutton-api-php/commits)
10+
[![Open Issues](https://img.shields.io/github/issues/bigbluebutton/bigbluebutton-api-php)](https://github.com/bigbluebutton/bigbluebutton-api-php/issues)
1011

1112
[![Build Status](https://scrutinizer-ci.com/g/bigbluebutton/bigbluebutton-api-php/badges/build.png?b=master)](https://scrutinizer-ci.com/g/bigbluebutton/bigbluebutton-api-php/build-status/master)
1213
[![Code Coverage](https://scrutinizer-ci.com/g/bigbluebutton/bigbluebutton-api-php/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/bigbluebutton/bigbluebutton-api-php/?branch=master)
13-
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/bigbluebutton/bigbluebutton-api-php/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/bigbluebutton/bigbluebutton-api-php/?branch=master)
14+
[![Code Quality](https://scrutinizer-ci.com/g/bigbluebutton/bigbluebutton-api-php/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/bigbluebutton/bigbluebutton-api-php/?branch=master)
15+
16+
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fbigbluebutton%2Fbigbluebutton-api-php.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fbigbluebutton%2Fbigbluebutton-api-php?ref=badge_shield)
17+
[![Website](https://img.shields.io/website-up-down-green-red/http/bigbluebutton.org.svg?label=bigbluebutton.org)](http://bigbluebutton.org)
18+
[![Follow @bigbluebutton](https://img.shields.io/badge/Twitter-%40bigbluebutton-blue?logo=twitter)](https://twitter.com/bigbluebutton)
1419

15-
[![@bigbluebutton on Twitter](https://img.shields.io/badge/twitter-%40bigbluebutton-blue.svg?style=flat)](https://twitter.com/bigbluebutton)
16-
![Website](https://img.shields.io/website-up-down-green-red/http/bigbluebutton.org.svg?label=BigBlueButton.org)
20+
---
1721

18-
[![PHP 8.1](https://img.shields.io/badge/php-8.1-f93.svg?style=flat-square)](https://www.php.net/supported-versions.php)
19-
[![PHP 8.2](https://img.shields.io/badge/php-8.2-9c9.svg?style=flat-square)](https://www.php.net/supported-versions.php)
20-
[![PHP 8.3](https://img.shields.io/badge/php-8.3-9c9.svg?style=flat-square)](https://www.php.net/supported-versions.php)
22+
The official **BigBlueButton PHP API Client** provides a developer-friendly wrapper to interact with
23+
the **BigBlueButton** API. Built for **PHP 8.1+**, this library simplifies integration and management of
24+
BigBlueButton servers in your PHP applications.
2125

22-
## Installation and usage
26+
---
2327

24-
The [wiki] contains all the documentation related to the PHP library. We have also written a samples to show a full
25-
install and usage example.
28+
## 📦 Installation & Usage
2629

27-
## Submitting bugs and feature requests
30+
You can find the full documentation, including sample usage and installation instructions, in our [Wiki].
2831

29-
Bugs and feature request are tracked on [GitHub](https://github.com/bigbluebutton/bigbluebutton-api-php/issues)
32+
```bash
33+
composer require bigbluebutton/bigbluebutton-api-php
34+
```
3035

31-
## Contributing guidelines
32-
### Code Quality 1: Style
36+
---
3337

34-
Make sure the code style configuration is applied by running PHPCS-Fixer.
38+
## 🐞 Issues & Feature Requests
3539

36-
```bash
37-
# using an alias
38-
$ composer code-fix
40+
Please use the [GitHub Issues](https://github.com/bigbluebutton/bigbluebutton-api-php/issues) tracker to report bugs or
41+
suggest new features.
3942

40-
# or the same w/o alias
41-
$ PHP_CS_FIXER_IGNORE_ENV=1 ./vendor/bin/php-cs-fixer fix --allow-risky yes
42-
```
43+
---
4344

44-
### Code Quality 2: Static code analysis
45-
PHPStan shall be used for static code analysis by running the command below:
45+
## 🧪 Code Quality & Testing
46+
47+
This project follows strict code quality checks before allowing commits. Here's how to contribute effectively:
48+
49+
### 1. Coding Style
4650

4751
```bash
48-
# using an alias
49-
$ composer code-check
52+
# Using Composer alias
53+
composer code-fix
5054

51-
# or the same w/o alias
52-
$ ./vendor/bin/phpstan analyse
55+
# Or directly
56+
PHP_CS_FIXER_IGNORE_ENV=1 ./vendor/bin/php-cs-fixer fix --allow-risky yes
5357
```
5458

55-
### Code Quality 3: Tests
56-
57-
For every implemented feature add unit tests and check all is green by running the command below.
59+
### 2. Static Analysis
5860

5961
```bash
60-
# using an alias
61-
$ composer code-test
62+
composer code-check
63+
# Or
64+
./vendor/bin/phpstan analyse
65+
```
6266

63-
# or the same w/o alias
67+
### 3. Running Tests
68+
69+
```bash
70+
composer code-test
71+
# Or
6472
./vendor/bin/phpunit
6573
```
6674

67-
To run a single test
75+
To run a specific test:
6876

6977
```bash
70-
# using an alias
71-
$ composer code-test -- --filter BigBlueButtonTest::testApiVersion
72-
73-
# or the same w/o alias
74-
./vendor/bin/phpunit --filter BigBlueButtonTest::testApiVersion
78+
composer code-test -- --filter BigBlueButtonTest::testApiVersion
7579
```
76-
A code-coverage report will be created along with the tests. This report will be stored in:
77-
````
78-
./var/coverage/
79-
````
80-
In case of trouble with the creation of the code-coverage report (e.g. local environment does not fulfill requirements)
81-
the creation can be skipped with:
80+
81+
To skip code coverage:
82+
8283
```bash
83-
# using an alias
84-
$ composer code-test -- --no-coverage
84+
composer code-test -- --no-coverage
85+
```
86+
87+
> **Coverage reports are stored in:** `./var/coverage/`
88+
89+
### 4. Configuration
90+
91+
To connect tests to your own BigBlueButton server, copy `.env` to `.env.local` and configure:
92+
93+
```env
94+
BBB_SERVER_BASE_URL=https://your-bbb-server.example.com/bigbluebutton/
95+
BBB_SECRET=your-secret
8596
```
8697

87-
**Remark:**
98+
---
99+
100+
## ✅ Pre-Commit Checks (CaptainHook)
88101

89-
Some test will connect to an existing BBB-server, which is specified in the `.env`-file. You
90-
can specify your own BBB-server by copy that file into the same folder and name it `.env.local`.
91-
Exchange the credentials `BBB_SERVER_BASE_URL` and `BBB_SECRET` to your server's values.
92-
Since this new file (`.env.local`) takes precedence over the main file (`.env`), you will now test
93-
with your own server.
102+
We use [CaptainHook](https://github.com/captainhookphp/captainhook) to enforce code quality:
94103

95-
### Automated checks while commiting a change
96-
To ensure code quality, a took called [CaptainHook](https://github.com/captainhookphp/captainhook?tab=readme-ov-file) will be launched when you are commiting a change and will intercept the commit, if the quality is not as expected. Once the quality of the code is improved the code can be commited (CaptainHook will check again).
104+
- ✔️ Commit message format ([beams](https://cbea.ms/git-commit/))
105+
- ✔️ Code style (PHPCS-Fixer)
106+
- ✔️ Static analysis (PHPStan)
107+
- ✔️ PHPUnit tests
97108

98-
Automated checks:
99-
1) Correct commit Message ([beams](https://cbea.ms/git-commit/)): Starting with capital letter, max. 50 characters and imperative mood (e.g. This change will: 'Refactor subsystem X for readability').
100-
2) Style: The code style will be checked with PHPCS-Fixer (same as above `composer code-fix`)
101-
3) Static Analyse: The code will be checked with PHPStan (same as above `composer code-check`)
102-
4) Test: PHPUnit will be executed to ensure the code is working (same as above `composer code-test`)
109+
You can manually run all pre-commit checks to avoid errors:
103110

104-
> **Tip:** To avoid interceptions by CaptainHook it is recommended to run the three commands prior your commit in order to pre-check the code quality.
111+
```bash
112+
composer code-fix
113+
composer code-check
114+
composer code-test
115+
```
116+
117+
> **Do not** skip checks using `--no-verify` unless absolutely necessary.
118+
119+
> CaptainHook should be installed automatically after the first composer install. If not:
120+
121+
```bash
122+
vendor/bin/captainhook install
123+
```
105124

106-
> **Danger:** Please avoid the deactivation of the automated checks by using the git flag `--no-verify` while commiting.
125+
---
107126

108-
> **Remark:** CaptainHook should be activated automatically with the first composer command (say `yes` to all questions). If you want to active it manually with `vendor/bin/captainhook install`.
127+
## 📝 License
109128

110-
[bbb]: http://bigbluebutton.org
111-
[composer]: https://getcomposer.org
112-
[INSTALL]: samples/README.md
113-
[wiki]: https://github.com/bigbluebutton/bigbluebutton-api-php/wiki
129+
This project is licensed under the terms of the [LGPL-3.0](LICENSE).
114130

115-
## License
116-
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fbigbluebutton%2Fbigbluebutton-api-php.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fbigbluebutton%2Fbigbluebutton-api-php?ref=badge_large)
131+
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fbigbluebutton%2Fbigbluebutton-api-php.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fbigbluebutton%2Fbigbluebutton-api-php?ref=badge_large)

0 commit comments

Comments
 (0)