Skip to content

Improved README.md #24

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
MekDrop merged 1 commit into from
Apr 20, 2025
Merged

Improved README.md #24

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
156 changes: 119 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,96 +1,178 @@
[![License](https://img.shields.io/github/license/impresscms-dev/generate-php-project-classes-list-file-action.svg)](LICENSE) [![GitHub release](https://img.shields.io/github/release/impresscms-dev/generate-php-project-classes-list-file-action.svg)](https://github.com/impresscms-dev/generate-php-project-classes-list-file-action/releases)

# Generate PHP project classes list file action
# Generate PHP Project Classes List File Action

GitHub action to generate a file with [PHP](https://php.net) project classes list (works only with [composer](https://getcomposer.org) projects). Built with Node.js 20.
A GitHub Action that generates a comprehensive list of classes in your [PHP](https://php.net) project. This action is designed to work with projects that use [Composer](https://getcomposer.org) for dependency management.

## Usage

To use this action in your project, create workflow in your project similar to this code (Note: some parts and arguments needs to be altered):
To integrate this action into your project, create a GitHub workflow file similar to the example below. You can customize the configuration to match your project's specific requirements:
```yaml
name: Generate PHP project class list as artifact
name: Generate PHP Class List

on:
push:
branches: [main]

jobs:
get_php_classes_list:
generate-class-list:
runs-on: ubuntu-latest
steps:
- name: Checkouting project code...
- name: Checkout repository
uses: actions/checkout@v4

- name: Install PHP
uses: shivammathur/setup-php@master
- name: Setup PHP environment
uses: shivammathur/setup-php@v2
with:
php-version: 8.4
extensions: curl, gd, pdo_mysql, json, mbstring, pcre, session
ini-values: post_max_size=256M
coverage: none
tools: composer:v2

- name: Install Composer dependencies (with dev)
run: composer install --no-progress --no-suggest --prefer-dist --optimize-autoloader
- name: Install Composer dependencies
run: composer install --no-progress --prefer-dist --optimize-autoloader

- name: Getting PHP classes list...
- name: Generate PHP classes list
uses: impresscms-dev/generate-php-project-classes-list-file-action@v2
with:
output_file: ./php-classes.lst
# Optional: specify a different path if composer.json is not in the root
# project_path: ./src

- uses: actions/upload-artifact@v4
- name: Upload classes list as artifact
uses: actions/upload-artifact@v4
with:
name: my-artifact
name: php-classes-list
path: ./php-classes.lst
```

## Arguments
## Prerequisites

This action supports such arguments (used in `with` keyword):
| Argument | Required | Default value | Description |
|-------------|----------|----------------------|------------------------------------------------------------|
| output_file | Yes | | File where to write classes list |
| project_path | No | . | Path to the directory containing composer.json |
Before using this action, ensure your workflow has:

1. PHP installed and configured
2. Composer setup and available

The example workflow above demonstrates how to properly configure these prerequisites using the [`shivammathur/setup-php`](https://github.com/marketplace/actions/setup-php-action) action.

## Configuration Options

This action accepts the following parameters in the `with` section of your workflow:

| Parameter | Required | Default | Description |
|-------------|----------|---------|-------------------------------------------------------|
| output_file | Yes | - | Destination file path for the generated classes list |
| project_path | No | `.` | Path to the directory containing your composer.json |

### Examples

**Basic Usage:**

Use this configuration when your `composer.json` file is located in the root directory of your repository. This is the most common setup for PHP projects.

```yaml
- name: Generate PHP classes list
uses: impresscms-dev/generate-php-project-classes-list-file-action@v2
with:
output_file: ./php-classes.lst
```

**With Custom Project Path:**

Use this configuration when your PHP project is in a subdirectory or when you have multiple PHP projects in a monorepo structure. This allows you to specify exactly which project's classes should be listed.

```yaml
- name: Generate PHP classes list
uses: impresscms-dev/generate-php-project-classes-list-file-action@v2
with:
output_file: ./php-classes.lst
project_path: ./src
```

**Generating Multiple Class Lists:**

For repositories with multiple PHP projects, you can run the action multiple times with different configurations to generate separate class lists for each project.

```yaml
- name: Generate main project classes list
uses: impresscms-dev/generate-php-project-classes-list-file-action@v2
with:
output_file: ./main-classes.lst
project_path: ./main

- name: Generate API project classes list
uses: impresscms-dev/generate-php-project-classes-list-file-action@v2
with:
output_file: ./api-classes.lst
project_path: ./api
```

## Development

### Setup
### Local Setup

Follow these steps to set up and work with the development environment for this action:

#### 1. Install Dependencies

First, install all required npm packages:

```bash
# Install dependencies
npm install
```

#### 2. Build the Action

Compile the source code using esbuild:

# Pack the action
```bash
npm run pack
```

This creates a bundled version of the action in the `dist/` directory. For GitHub Actions, this directory must be committed to the repository as it contains the executable code that runs when others use this action.

# Run tests
Note: If you forget to update the `dist/` folder after making changes, don't worry - there's a CI workflow that automatically builds and updates it when pull requests are submitted.

#### 3. Run Tests

Execute the test suite to verify functionality:

```bash
npm test
```

# Lint code (both source and tests)
npm run lint
#### 4. Code Quality

# Fix lint issues (both source and tests)
npm run lint:fix
Check code quality with ESLint:

# Run all checks (lint, pack, test)
npm run all
```bash
npm run lint
```

### Packaging
Automatically fix linting issues when possible:

This action uses [ncc](https://github.com/vercel/ncc) to compile the Node.js code and dependencies into a single file in the `dist/` folder. This allows the action to run quickly and reliably.
```bash
npm run lint:fix
```

#### 5. Complete Verification

After making changes to the code, you should run:
Run all checks (linting, building, and testing) in one command:

```bash
npm run pack
npm run all
```

The `dist/` folder should be committed to the repository. This is a requirement for GitHub Actions so that users can run the action without having to build it themselves.
This is particularly useful before submitting a pull request.

## Contributing

## How to contribute?
Contributions are welcome! To contribute to this project:

If you want to add some functionality or fix bugs, you can fork, change and create pull request. If you not sure how this works, try [interactive GitHub tutorial](https://skills.github.com).
1. [Fork the repository](https://github.com/impresscms-dev/generate-php-project-classes-list-file-action/fork)
2. Create a feature branch and implement your changes
3. Ensure tests pass and code meets quality standards
4. [Submit a pull request](https://github.com/impresscms-dev/generate-php-project-classes-list-file-action/compare)

If you found any bug or have some questions, use [issues tab](https://github.com/impresscms-dev/generate-php-project-classes-list-file-action/issues) and write there your questions.
For bug reports, questions, or feature requests, please use the [issues section](https://github.com/impresscms-dev/generate-php-project-classes-list-file-action/issues).